canon 0.1.6 → 0.1.7

data/docs/guides/index.adoc

@@ -0,0 +1,181 @@
+---
+layout: default
+title: Guides
+nav_order: 8
+has_children: true
+---
+= Guides
+
+Task-oriented tutorials for common Canon use cases.
+
+== Overview
+
+This section provides step-by-step guides for accomplishing specific tasks with Canon. Each guide walks you through a complete workflow from start to finish.
+
+Unlike reference documentation that explains individual features, these guides show you how to combine features to solve real problems.
+
+== Available Guides
+
+link:testing-xml-generation[**Testing XML Generation**]::
+How to use Canon in RSpec tests to validate generated XML output.
++
+Covers: RSpec matchers, match profiles, handling whitespace, debugging failures.
+
+link:debugging-test-failures[**Debugging Test Failures**]::
+Strategies for diagnosing and fixing test failures when comparing documents.
++
+Covers: Verbose mode, character visualization, match dimension tuning, common pitfalls.
+
+link:migrating-from-xmldiff[**Migrating from XMLDiff**]::
+Guide for users switching from other XML comparison tools.
++
+Covers: Feature mapping, option translation, behavior differences, migration checklist.
+
+link:performance-optimization[**Performance Optimization**]::
+Techniques for improving comparison performance on large documents.
++
+Covers: Algorithm selection, size limits, preprocessing strategies, batch processing.
+
+link:custom-comparators[**Building Custom Comparators**]::
+How to extend Canon with custom comparison logic for specialized formats.
++
+Covers: Comparator interface, adapter pattern, integration, testing.
+
+== By Use Case
+
+=== Testing and QA
+
+**Writing reliable XML tests**::
+link:testing-xml-generation[Testing XML Generation] shows how to use Canon's RSpec matchers for robust testing.
+
+**Debugging test failures**::
+link:debugging-test-failures[Debugging Test Failures] provides systematic troubleshooting strategies.
+
+**Comparing configuration files**::
+Use link:../features/match-options/profiles[Match Profiles] with the `spec_friendly` profile.
+
+=== Migration and Integration
+
+**Switching from another tool**::
+link:migrating-from-xmldiff[Migrating from XMLDiff] helps you transition smoothly.
+
+**Integrating into CI/CD**::
+See link:../interfaces/cli/[CLI Reference] for command-line usage in pipelines.
+
+**Adding to existing test suite**::
+link:testing-xml-generation[Testing XML Generation] covers integration patterns.
+
+=== Performance and Scale
+
+**Handling large files**::
+link:performance-optimization[Performance Optimization] shows strategies for large documents.
+
+**Batch processing**::
+See link:performance-optimization#batch-processing[Batch Processing] section.
+
+**Optimizing comparison speed**::
+link:performance-optimization#algorithm-selection[Algorithm Selection] explains trade-offs.
+
+=== Customization and Extension
+
+**Custom comparison logic**::
+link:custom-comparators[Building Custom Comparators] walks through the process.
+
+**Format-specific handling**::
+See link:../advanced/extending-canon[Extending Canon] for adapter development.
+
+== Guide Structure
+
+Each guide follows this structure:
+
+**Overview**::
+What you'll learn and prerequisites.
+
+**Problem**::
+The real-world problem this guide solves.
+
+**Solution**::
+Step-by-step walkthrough with code examples.
+
+**Explanation**::
+Why the solution works and alternatives to consider.
+
+**Summary**::
+Key takeaways and next steps.
+
+== Prerequisites
+
+Most guides assume:
+
+* Ruby 2.7 or higher installed
+* Basic familiarity with Canon concepts
+* Understanding of the format you're working with
+
+If you're new to Canon, start with link:../getting-started/[Getting Started] first.
+
+== Common Patterns
+
+=== Test-Friendly Comparison
+
+[source,ruby]
+----
+# Ignore formatting differences in tests
+expect(actual_xml).to be_xml_equivalent_to(expected_xml,
+  match_profile: :spec_friendly
+)
+----
+
+See link:testing-xml-generation#test-friendly-matching[Test-Friendly Matching].
+
+=== Detailed Debugging
+
+[source,ruby]
+----
+# Get detailed diff output
+result = Canon::Comparison.compare(expected, actual,
+  verbose: true,
+  visualize_whitespace: true,
+  context_lines: 10
+)
+puts result.diff
+----
+
+See link:debugging-test-failures#verbose-output[Verbose Output].
+
+=== Performance Tuning
+
+[source,ruby]
+----
+# Optimize for large files
+Canon::Comparison.equivalent?(doc1, doc2,
+  preprocessing: :none,  # Skip preprocessing
+  diff_algorithm: :dom,  # Use faster algorithm
+  max_nodes: 50000       # Increase limit if needed
+)
+----
+
+See link:performance-optimization#tuning-options[Tuning Options].
+
+== Getting Help
+
+**Can't find what you need?**::
+Check link:../reference/[Reference] for complete option listings.
+
+**Need conceptual understanding?**::
+See link:../understanding/[Understanding Canon] for architectural details.
+
+**Want to contribute a guide?**::
+See link:../contributing[Contributing Guidelines].
+
+== Next Steps
+
+* Choose a guide that matches your current task
+* Follow along with the code examples
+* Experiment with variations
+* Share your learnings with the community
+
+== See Also
+
+* link:../getting-started/[Getting Started] - Basic Canon usage
+* link:../features/[Features] - Configuration options
+* link:../reference/[Reference] - Complete option listings

data/docs/{CLI.adoc → interfaces/cli/index.adoc}

@@ -1,8 +1,9 @@
 ---
 layout: default
-title: Command-Line Interface
-nav_order: 11
-parent: Basic Usage
+title: CLI Reference
+parent: Interfaces
+nav_order: 2
+has_children: true
 ---
 = Canon command-line interface
 :toc:
@@ -13,9 +14,9 @@ parent: Basic Usage
 This document describes Canon's command-line interface (CLI). The `canon`
 command provides file formatting and comparison capabilities.
 
-For Ruby API usage, see link:RUBY_API[Ruby API documentation].
+For Ruby API usage, see link:../ruby-api/[Ruby API documentation].
 
-For RSpec testing, see link:RSPEC[RSpec documentation].
+For RSpec testing, see link:../rspec/[RSpec documentation].
 
 == General
 
@@ -197,7 +198,7 @@ structural changes
 `by-line`:: (default for HTML, optional for XML) Line-by-line diff after
 canonicalization
 
-See link:MODES[Diff modes] for details.
+See link:../../understanding/diff-modes/[Diff modes] for details.
 
 === Format options
 
@@ -213,6 +214,10 @@ See link:MODES[Diff modes] for details.
 `-v, --verbose`:: Show detailed differences (default: just show if files
 differ)
 
+`--diff-algorithm ALGORITHM`:: Diff algorithm to use: `dom` (default) or
+`semantic`. DOM uses positional matching, semantic uses tree-based matching
+with operation detection.
+
 `--by-line`:: Use line-by-line diff for XML (default: by-object mode)
 
 `--text-content BEHAVIOR`:: How to compare text content: `strict`,
@@ -239,7 +244,7 @@ values: `strict`, `normalize`, or `ignore` (XML/HTML only)
 `--match-profile PROFILE`:: Use predefined match profile: `strict`,
 `rendered`, `spec_friendly`, or `content_only`
 
-See link:MATCH_OPTIONS[Match options] for detailed dimension reference.
+See link:../../features/match-options/[Match options] for detailed dimension reference.
 
 === Output options
 
@@ -249,7 +254,7 @@ See link:MATCH_OPTIONS[Match options] for detailed dimension reference.
 
 `--diff-grouping-lines N`:: Group changes within N lines into blocks
 
-See link:DIFF_FORMATTING[Diff formatting] for details.
+See link:../../features/diff-formatting/[Diff formatting] for details.
 
 === Exit codes
 
@@ -486,8 +491,8 @@ $ canon --version
 
 == See also
 
-* link:RUBY_API[Ruby API documentation]
-* link:RSPEC[RSpec matchers]
-* link:MATCH_OPTIONS[Match options reference]
-* link:MODES[Diff modes]
-* link:DIFF_FORMATTING[Diff formatting options]
+* link:../ruby-api/[Ruby API documentation]
+* link:../rspec/[RSpec matchers]
+* link:../../features/match-options/[Match options reference]
+* link:../../understanding/diff-modes/[Diff modes]
+* link:../../features/diff-formatting/[Diff formatting options]

data/docs/interfaces/index.adoc

@@ -0,0 +1,101 @@
+---
+layout: default
+title: Interfaces
+nav_order: 3
+has_children: true
+---
+= Interfaces
+
+Learn how to use Canon through different interfaces.
+
+== Overview
+
+Canon provides three main interfaces for different use cases:
+
+link:ruby-api/[**Ruby API**]::
+Integrate Canon into Ruby applications for programmatic formatting and comparison.
+
+link:cli/[**Command-Line Interface**]::
+Use Canon from the terminal for one-off tasks and shell scripting.
+
+link:rspec/[**RSpec Matchers**]::
+Test XML, JSON, and YAML generation with semantic matchers.
+
+== Choosing an Interface
+
+**Use Ruby API when**::
+* Integrating into a Ruby application
+* Need programmatic control
+* Building custom tooling
+* Processing multiple files
+
+**Use CLI when**::
+* Running one-off comparisons
+* Shell scripting
+* CI/CD pipelines
+* Quick formatting tasks
+
+**Use RSpec when**::
+* Writing tests
+* Validating generated output
+* TDD/BDD workflows
+* Continuous integration
+
+== Common Patterns Across Interfaces
+
+All interfaces share the same core concepts:
+
+* **Formats**: XML, HTML, JSON, YAML
+* **Operations**: Format (canonicalize/pretty-print) and Compare
+* **Options**: Match dimensions, profiles, preprocessing
+* **Output**: Color-coded diffs, character visualization
+
+The interface you choose determines **how** you invoke these features, but the underlying behavior is consistent.
+
+== Quick Examples
+
+=== Format a File
+
+**Ruby**:
+[source,ruby]
+----
+Canon.format(xml_string, :xml, mode: :pretty)
+----
+
+**CLI**:
+[source,bash]
+----
+canon format file.xml --mode pretty
+----
+
+=== Compare Files
+
+**Ruby**:
+[source,ruby]
+----
+Canon::Comparison.equivalent?(doc1, doc2)
+----
+
+**CLI**:
+[source,bash]
+----
+canon diff file1.xml file2.xml
+----
+
+**RSpec**:
+[source,ruby]
+----
+expect(actual_xml).to be_xml_equivalent_to(expected_xml)
+----
+
+== Next Steps
+
+* Choose your primary interface and dive into its documentation
+* Review link:../features/match-options/[Match Options] to understand configuration
+* Check link:../guides/[Guides] for task-oriented tutorials
+
+== See Also
+
+* link:../getting-started/quick-start[Quick Start] - Basic usage examples
+* link:../features/match-options/[Match Options] - Customizing comparison behavior
+* link:../understanding/architecture[Architecture] - How Canon works internally