canon 0.1.23 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08086e588946bb0f5f39a8235984058b5a5e8aea956b9652e0e366ff84500232'
-  data.tar.gz: bb078d67c1a68da1ca88b3d29fde336e291b0ff95186ade125ee1ccfb1a82de4
+  metadata.gz: 10234a14be49f993f58acac6d82bb6e8ca409d309bcd8446296f32f60ad6380f
+  data.tar.gz: 80e29ddf981d17f0fcd5812921f6ec1fbdf056b3ae673dc4d3d94c9979cddc21
 SHA512:
-  metadata.gz: 35f7888d948f86fa4b504b060ee6d9976dc38b32232e8c86b9b8986ee08448cdad265fe4d091e810e5f63f0b0702e125317e07d15761b5cd6404905190546234
-  data.tar.gz: 4f57564289fdff8c73020f3ed9f9184b363688062cf1b89baea79f0d25c57905bcbc225b5e946afeb30305b91402b557ae65ce61b99a0d63b8bb1c569ec2d57f
+  metadata.gz: bc63b5a8dae56a06781d8588809e8356eea618fdcdb13b933ea4c8a3c4f221201c05070a3ce100945c9f81ef6f122b73ff6ac723441aa2b3cbcc5fd31e8fee63
+  data.tar.gz: fbcb9ceb782f7847e6f2c6afba275f7d68da410d253b6f34f263b5c91803a3fbaff031de9b2dda5b8787fc37d0c82e1cea97d3ae1489d507eaad969168a107a1

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-04-01 00:03:16 UTC using RuboCop version 1.86.0.
+# on 2026-04-12 07:40:40 UTC using RuboCop version 1.86.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -11,39 +11,147 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'canon.gemspec'
 
-# Offense count: 2
+# Offense count: 49
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: with_first_argument, with_fixed_indentation
+Layout/ArgumentAlignment:
+  Exclude:
+    - 'lib/canon/comparison/whitespace_sensitivity.rb'
+    - 'lib/canon/comparison/xml_comparator.rb'
+    - 'lib/canon/comparison/xml_node_comparison.rb'
+    - 'lib/canon/config.rb'
+    - 'lib/canon/diff/diff_classifier.rb'
+    - 'lib/canon/diff_formatter.rb'
+    - 'lib/canon/diff_formatter/diff_detail_formatter/dimension_formatter.rb'
+    - 'lib/canon/pretty_printer/xml_normalized.rb'
+    - 'spec/canon/config/profile_loader_spec.rb'
+    - 'spec/canon/config/profile_spec.rb'
+    - 'spec/canon/diff_formatter/diff_detail_formatter_spec.rb'
+    - 'spec/canon/diff_formatter/pretty_diff_spec.rb'
+    - 'spec/canon/diff_formatter/show_diffs_filtering_spec.rb'
+    - 'spec/canon/pretty_printer/xml_normalized_spec.rb'
+
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: with_first_element, with_fixed_indentation
+Layout/ArrayAlignment:
+  Exclude:
+    - 'lib/canon/comparison/match_options/base_resolver.rb'
+    - 'lib/canon/comparison/match_options/xml_resolver.rb'
+    - 'spec/canon/config/profile_spec.rb'
+
+# Offense count: 16
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyleAlignWith.
 # SupportedStylesAlignWith: either, start_of_block, start_of_line
 Layout/BlockAlignment:
   Exclude:
-    - 'lib/canon/tree_diff/matchers/hash_matcher.rb'
-    - 'spec/canon/hash_matcher_regression_spec.rb'
+    - 'lib/canon/diff_formatter/diff_detail_formatter/node_utils.rb'
+    - 'lib/canon/pretty_printer/xml_normalized.rb'
+    - 'spec/canon/config/profile_loader_spec.rb'
+    - 'spec/canon/diff_formatter/display_preprocessing_spec.rb'
+    - 'spec/canon/diff_formatter/pretty_diff_spec.rb'
+    - 'spec/canon/diff_formatter/show_diffs_filtering_spec.rb'
+    - 'spec/canon/pretty_printer/xml_normalized_spec.rb'
 
-# Offense count: 2
+# Offense count: 16
 # This cop supports safe autocorrection (--autocorrect).
 Layout/BlockEndNewline:
   Exclude:
-    - 'lib/canon/tree_diff/matchers/hash_matcher.rb'
-    - 'spec/canon/hash_matcher_regression_spec.rb'
+    - 'lib/canon/diff_formatter/diff_detail_formatter/node_utils.rb'
+    - 'lib/canon/pretty_printer/xml_normalized.rb'
+    - 'spec/canon/config/profile_loader_spec.rb'
+    - 'spec/canon/diff_formatter/display_preprocessing_spec.rb'
+    - 'spec/canon/diff_formatter/pretty_diff_spec.rb'
+    - 'spec/canon/diff_formatter/show_diffs_filtering_spec.rb'
+    - 'spec/canon/pretty_printer/xml_normalized_spec.rb'
 
-# Offense count: 4
+# Offense count: 5
+# This cop supports safe autocorrection (--autocorrect).
+Layout/ClosingParenthesisIndentation:
+  Exclude:
+    - 'lib/canon/config/profile_loader.rb'
+    - 'lib/canon/diff/diff_classifier.rb'
+    - 'spec/canon/config/profile_loader_spec.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+Layout/ElseAlignment:
+  Exclude:
+    - 'lib/canon/diff_formatter/diff_detail_formatter/dimension_formatter.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleAlignWith.
+# SupportedStylesAlignWith: keyword, variable, start_of_line
+Layout/EndAlignment:
+  Exclude:
+    - 'lib/canon/diff_formatter/diff_detail_formatter/dimension_formatter.rb'
+
+# Offense count: 5
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: consistent, consistent_relative_to_receiver, special_for_inner_method_call, special_for_inner_method_call_in_parentheses
+Layout/FirstArgumentIndentation:
+  Exclude:
+    - 'lib/canon/config/profile_loader.rb'
+    - 'lib/canon/diff/diff_classifier.rb'
+    - 'spec/canon/config/profile_loader_spec.rb'
+
+# Offense count: 30
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowMultipleStyles, EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle.
+# SupportedHashRocketStyles: key, separator, table
+# SupportedColonStyles: key, separator, table
+# SupportedLastArgumentHashStyles: always_inspect, always_ignore, ignore_implicit, ignore_explicit
+Layout/HashAlignment:
+  Exclude:
+    - 'spec/canon/diff_formatter/diff_detail_formatter_spec.rb'
+    - 'spec/canon/diff_formatter/display_preprocessing_spec.rb'
+    - 'spec/canon/diff_formatter/pretty_diff_spec.rb'
+    - 'spec/canon/diff_formatter/show_diffs_filtering_spec.rb'
+    - 'spec/canon/pretty_printer/xml_normalized_spec.rb'
+
+# Offense count: 36
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Width, EnforcedStyleAlignWith, AllowedPatterns.
 # SupportedStylesAlignWith: start_of_line, relative_to_receiver
 Layout/IndentationWidth:
   Exclude:
-    - 'lib/canon/tree_diff/matchers/hash_matcher.rb'
-    - 'spec/canon/hash_matcher_regression_spec.rb'
+    - 'lib/canon/diff_formatter/diff_detail_formatter/dimension_formatter.rb'
+    - 'lib/canon/diff_formatter/diff_detail_formatter/node_utils.rb'
+    - 'lib/canon/pretty_printer/xml_normalized.rb'
+    - 'spec/canon/config/profile_loader_spec.rb'
+    - 'spec/canon/diff_formatter/display_preprocessing_spec.rb'
+    - 'spec/canon/diff_formatter/pretty_diff_spec.rb'
+    - 'spec/canon/diff_formatter/show_diffs_filtering_spec.rb'
+    - 'spec/canon/pretty_printer/xml_normalized_spec.rb'
 
-# Offense count: 1103
+# Offense count: 1375
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Enabled: false
 
-# Offense count: 55
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: symmetrical, new_line, same_line
+Layout/MultilineMethodCallBraceLayout:
+  Exclude:
+    - 'lib/canon/config/profile_loader.rb'
+    - 'lib/canon/diff/diff_classifier.rb'
+
+# Offense count: 57
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowInHeredoc.
+Layout/TrailingWhitespace:
+  Enabled: false
+
+# Offense count: 56
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
 Lint/DuplicateBranch:
   Enabled: false
@@ -88,7 +196,7 @@ Lint/UselessConstantScoping:
   Exclude:
     - 'lib/canon/diff_formatter/theme.rb'
 
-# Offense count: 298
+# Offense count: 309
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
@@ -99,27 +207,27 @@ Metrics/AbcSize:
 Metrics/BlockLength:
   Max: 92
 
-# Offense count: 1
+# Offense count: 3
 # Configuration parameters: CountBlocks, CountModifierForms.
 Metrics/BlockNesting:
   Max: 4
 
-# Offense count: 262
+# Offense count: 272
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 485
+# Offense count: 498
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 146
 
-# Offense count: 56
+# Offense count: 58
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
   Max: 10
 
-# Offense count: 213
+# Offense count: 219
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false
@@ -152,13 +260,13 @@ Performance/CollectionLiteralInLoop:
     - 'lib/canon/xml/xml_base_handler.rb'
     - 'spec/canon/diff/diff_node_mapper_comments_spec.rb'
 
-# Offense count: 71
+# Offense count: 82
 # Configuration parameters: Prefixes, AllowedPatterns.
 # Prefixes: when, with, without
 RSpec/ContextWording:
   Enabled: false
 
-# Offense count: 34
+# Offense count: 37
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Enabled: false
@@ -169,7 +277,7 @@ RSpec/DescribeMethod:
     - 'spec/canon/comparison/multiple_differences_spec.rb'
     - 'spec/canon/diff_formatter/character_map_customization_spec.rb'
 
-# Offense count: 741
+# Offense count: 804
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 44
@@ -183,7 +291,7 @@ RSpec/ExpectActual:
     - 'spec/canon/rspec_matchers_spec.rb'
     - 'spec/canon/string_matcher_spec.rb'
 
-# Offense count: 175
+# Offense count: 177
 # Configuration parameters: Max, AllowedIdentifiers, AllowedPatterns.
 RSpec/IndexedLet:
   Exclude:
@@ -221,14 +329,14 @@ RSpec/MultipleDescribes:
   Exclude:
     - 'spec/canon/comparison/match_options_spec.rb'
 
-# Offense count: 595
+# Offense count: 654
 RSpec/MultipleExpectations:
   Max: 15
 
-# Offense count: 71
+# Offense count: 93
 # Configuration parameters: AllowSubject.
 RSpec/MultipleMemoizedHelpers:
-  Max: 13
+  Max: 16
 
 # Offense count: 17
 # Configuration parameters: EnforcedStyle, IgnoreSharedExamples.
@@ -239,7 +347,7 @@ RSpec/NamedSubject:
     - 'spec/canon/pretty_printer/json_spec.rb'
     - 'spec/canon/pretty_printer/xml_spec.rb'
 
-# Offense count: 40
+# Offense count: 50
 # Configuration parameters: AllowedGroups.
 RSpec/NestedGroups:
   Max: 4
@@ -273,7 +381,7 @@ RSpec/SpecFilePathFormat:
     - 'spec/canon/yaml/formatter_spec.rb'
     - 'spec/xml_c14n_spec.rb'
 
-# Offense count: 128
+# Offense count: 131
 # Configuration parameters: IgnoreNameless, IgnoreSymbolicNames.
 RSpec/VerifiedDoubles:
   Exclude:
@@ -285,7 +393,7 @@ RSpec/VerifiedDoubles:
     - 'spec/canon/diff_formatter/diff_detail_formatter_spec.rb'
     - 'spec/canon/tree_diff/operation_converter_spec.rb'
 
-# Offense count: 2
+# Offense count: 25
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, ProceduralMethods, FunctionalMethods, AllowedMethods, AllowedPatterns, AllowBracesOnProceduralOneLiners, BracesRequiredMethods.
 # SupportedStyles: line_count_based, semantic, braces_for_chaining, always_braces
@@ -294,8 +402,13 @@ RSpec/VerifiedDoubles:
 # AllowedMethods: lambda, proc, it
 Style/BlockDelimiters:
   Exclude:
-    - 'lib/canon/tree_diff/matchers/hash_matcher.rb'
-    - 'spec/canon/hash_matcher_regression_spec.rb'
+    - 'lib/canon/diff_formatter/diff_detail_formatter/node_utils.rb'
+    - 'lib/canon/pretty_printer/xml_normalized.rb'
+    - 'spec/canon/config/profile_loader_spec.rb'
+    - 'spec/canon/diff_formatter/display_preprocessing_spec.rb'
+    - 'spec/canon/diff_formatter/pretty_diff_spec.rb'
+    - 'spec/canon/diff_formatter/show_diffs_filtering_spec.rb'
+    - 'spec/canon/pretty_printer/xml_normalized_spec.rb'
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
@@ -319,6 +432,18 @@ Style/IdenticalConditionalBranches:
     - 'lib/canon/diff_formatter/by_object/base_formatter.rb'
     - 'lib/canon/diff_formatter/legend.rb'
 
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+Style/MultilineIfModifier:
+  Exclude:
+    - 'lib/canon/pretty_printer/xml_normalized.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+Style/MultilineTernaryOperator:
+  Exclude:
+    - 'lib/canon/diff_formatter/diff_detail_formatter/dimension_formatter.rb'
+
 # Offense count: 1
 # Configuration parameters: AllowedMethods.
 # AllowedMethods: respond_to_missing?

data/docs/INDEX.adoc

@@ -98,6 +98,7 @@ Choose your interface:
 === Level 4: Master Features (1 hour)
 
 . link:features/match-options/[Match options and profiles]
+. link:features/configuration-profiles/[Configuration profiles] - YAML-based presets with element-level whitespace control
 . link:features/canonicalization/[Format-specific canonicalization]
 . link:features/diff-formatting/[Customizing diff output]
 
@@ -111,6 +112,7 @@ Choose your interface:
 
 * link:reference/options-across-interfaces[Options Across Interfaces] - Same options in CLI, Ruby API, and RSpec
 * link:reference/environment-variables[Environment Variables] - Configure Canon via ENV variables
+* link:features/configuration-profiles/[Configuration Profiles] - YAML presets with element-level whitespace control
 * link:features/match-options/profiles[Match Profiles] - Pre-configured comparison strategies
 * link:features/diff-formatting/colors-and-symbols[Color-Coded Diffs] - Understanding diff output
 * link:features/environment-configuration/size-limits[Size Limits] - Preventing hangs on large files
@@ -135,5 +137,7 @@ See link:contributing[Contributing to Documentation]
 * 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 link:https://github.com/lutaml/canon/blob/main/CHANGELOG.md[Full Changelog]

data/docs/advanced/diff-classification.adoc

@@ -324,7 +324,7 @@ html2 = '<code>indented</code><p>text</p>'
 Canon::Comparison.equivalent?(html1, html2,
   format: :html,
   match: {
-    whitespace_insensitive_elements: [:code],
+    strip_whitespace_elements: [:code],
   }
 )
 # => true
@@ -423,9 +423,10 @@ def classify(diff_node)
   end
 
   # SECOND: Handle content-level formatting for text_content with :normalize
+  # Skipped for :preserve elements (<pre>, <code>, etc.) where whitespace is always normative
   if diff_node.dimension == :text_content &&
       profile.send(:behavior_for, :text_content) == :normalize &&
-      !inside_whitespace_sensitive_element?(diff_node) &&
+      !inside_preserve_element?(diff_node) &&
       formatting_only_diff?(diff_node)
     diff_node.formatting = true
     diff_node.normative = false

data/docs/features/configuration-profiles.adoc

@@ -0,0 +1,288 @@
+---
+title: Configuration Profiles
+parent: Features
+nav_order: 7
+---
+= Configuration profiles
+:toc:
+:toclevels: 3
+
+== Purpose
+
+Configuration profiles bundle many settings into a single named preset,
+eliminating repetitive configuration blocks across multiple gems.
+Instead of 60+ lines of per-format settings, use one line:
+
+[source,ruby]
+----
+Canon::Config.instance.profile = :metanorma
+----
+
+Profiles are defined in YAML files and support inheritance, so a debug
+variant can extend a base profile with only the differences.
+
+== Built-in profiles
+
+[cols="1,3"]
+|===
+| Profile | Description
+
+| `:metanorma`
+| Standard Metanorma spec configuration. Sets preprocessing to `:format`,
+  match profile to `:spec_friendly`, diff algorithm to `:dom`, canonical
+  display format, normalized pretty-print display preprocessing,
+  and XML-specific whitespace element lists.
+
+| `:metanorma_debug`
+| Extends `:metanorma` with debug output enabled
+  (`show_prettyprint_received: true`).
+|===
+
+List all available profiles programmatically:
+
+[source,ruby]
+----
+Canon::Config::ProfileLoader.available_profiles
+# => [:metanorma, :metanorma_debug]
+----
+
+== Element-level whitespace classification
+
+The metanorma profile's key feature is its **element-level whitespace classification**.
+This controls how whitespace differences within specific elements are treated:
+
+**Three-way classification:**
+
+* **Preserve** (`:preserve`) — Every whitespace character is significant. Use for elements
+  where exact whitespace matters (like `<pre>`, `<code>`).
+
+* **Collapse** (`:collapse`) — Presence matters but whitespace form doesn't.
+  `"  hello  "` equals `"hello"`. Differences are formatting-only (informative).
+  Use for elements like `<p>`, `<li>`, `<td>` in prose documents.
+
+* **Strip** (`:strip`) — Whitespace is structural noise, dropped entirely.
+  The default for XML elements not in any list.
+
+**Metanorma profile element lists:**
+
+[source,ruby]
+----
+# In metanorma profile
+Canon::Config.instance.profile = :metanorma
+Canon::Config.instance.xml.match.collapse_whitespace_elements
+# => ["p", "title", "name", "td", "th", "dt", "dd", "li", ...]
+
+Canon::Config.instance.xml.match.preserve_whitespace_elements
+# => ["body", "passthrough"]
+----
+
+**How it works with `text_content: :normalize`:**
+
+[source,ruby]
+----
+# With metanorma profile: <p> is in collapse_whitespace_elements
+Canon::Config.instance.profile = :metanorma
+
+# These are EQUIVALENT (whitespace in <p> is formatting-only)
+Canon::Comparison.equivalent?('<p>  hello  </p>', '<p>hello</p>')
+# => true
+
+# But <body> is in preserve_whitespace_elements — every character matters
+# These are NOT EQUIVALENT (whitespace in <body> is normative)
+Canon::Comparison.equivalent?('<body>  hello  </body>', '<body>hello</body>')
+# => false
+----
+
+**Why this matters:**
+
+In Metanorma/DocBook documents, elements like `<p>`, `<li>`, `<td>` contain prose
+where whitespace formatting (extra spaces, line breaks) is irrelevant. But `<body>`
+or `<passthrough>` contain code or exact whitespace that matters.
+
+Without element-level classification, you'd have to choose:
+- `text_content: :normalize` — ignores ALL whitespace, too permissive
+- `text_content: :strict` — requires exact match everywhere, too strict
+
+Element-level classification gives you fine-grained control.
+
+== Usage
+
+=== Programmatic (Ruby API)
+
+Use a **Symbol** for built-in profiles and a **String** for file paths:
+
+[source,ruby]
+----
+# Built-in profile (Symbol)
+Canon::Config.instance.profile = :metanorma
+
+# Local YAML file (String)
+Canon::Config.instance.profile = "/path/to/my_profile.yml"
+Canon::Config.instance.profile = "~/my_canon_profile.yml"
+Canon::Config.instance.profile = "config/canon_profile.yml"
+
+# Or in a configure block
+Canon::Config.configure do |cfg|
+  cfg.profile = :metanorma
+  # Override individual settings after profile if needed
+  cfg.xml.diff.verbose_diff = true
+end
+
+# Clear the profile (revert to defaults + programmatic values)
+Canon::Config.instance.profile = nil
+----
+
+IMPORTANT: The type of the value determines how it is resolved:
+**Symbols** are looked up as built-in profile names;
+**Strings** are treated as file paths (with `~` expansion and relative
+path resolution against the working directory).
+
+Local YAML files can inherit from built-in profiles (see <<inheritance>>).
+
+=== Environment variable
+
+Set `CANON_CONFIG_PROFILE` to apply a profile automatically on
+initialization:
+
+[source,bash]
+----
+# Built-in profile
+CANON_CONFIG_PROFILE=metanorma bundle exec rspec
+
+# File path
+CANON_CONFIG_PROFILE=~/my_profile.yml bundle exec rspec
+----
+
+NOTE: `CANON_CONFIG_PROFILE` is distinct from `CANON_PROFILE`, which
+controls the match profile (comparison behavior). The config profile
+controls all settings at once.
+
+== Priority chain
+
+With profiles, the resolution chain becomes four layers:
+
+[source]
+----
++------------------------------------+
+| 1. Environment Variables           | <- Highest Priority
+|    (CANON_XML_DIFF_ALGORITHM)      |
++------------------------------------+
+               | overrides
++------------------------------------+
+| 2. Programmatic Configuration      |
+|    (config.xml.diff.algorithm=)    |
++------------------------------------+
+               | overrides
++------------------------------------+
+| 3. Profile Values                  |
+|    (from YAML profile file)        |
++------------------------------------+
+               | overrides
++------------------------------------+
+| 4. Default Values                  | <- Lowest Priority
+|    (defined in Canon::Config)      |
++------------------------------------+
+----
+
+This means:
+
+* ENV variables always win (useful for CI overrides)
+* Programmatic setter calls override profile values
+* Profile values override built-in defaults
+* Clearing the profile (`cfg.profile = nil`) removes only layer 3
+
+[[inheritance]]
+== Profile inheritance
+
+A profile can inherit from another using the `inherits` key:
+
+[source,yaml]
+----
+name: my_debug
+inherits: metanorma
+
+shared:
+  diff:
+    verbose_diff: true
+    show_prettyprint_received: true
+----
+
+Inheritance rules:
+
+* Parent values are loaded first, then child values are deep-merged on top
+* Hashes are merged recursively (child keys override parent keys)
+* Arrays are replaced entirely (not concatenated)
+* Single-parent inheritance only
+* Cycle detection prevents infinite loops
+* Local files can inherit from built-in profiles by name
+
+== Creating custom profiles
+
+=== YAML file format
+
+[source,yaml]
+----
+---
+name: my_profile              # <1>
+description: My custom config # <2>
+inherits: metanorma           # <3>
+
+shared:                        # <4>
+  preprocessing: format
+  match:
+    profile: spec_friendly
+  diff:
+    algorithm: dom
+    context_lines: 5
+    verbose_diff: false
+
+formats:                       # <5>
+  xml:
+    match:
+      collapse_whitespace_elements:
+        - p
+        - title
+        - td
+      preserve_whitespace_elements:
+        - body
+        - passthrough
+  html:
+    diff:
+      show_raw_inputs: true
+----
+<1> Profile name (metadata)
+<2> Description (metadata)
+<3> Optional: inherit from another profile (name or path)
+<4> `shared` settings apply to all formats (xml, html, json, yaml, string)
+<5> `formats.<name>` settings override `shared` for that specific format
+
+=== Attribute mapping
+
+Profile YAML keys map directly to Canon configuration accessors:
+
+[cols="2,2"]
+|===
+| YAML path | Ruby equivalent
+
+| `shared.preprocessing`
+| `cfg.xml.preprocessing = :format`
+
+| `shared.match.profile`
+| `cfg.xml.match.profile = :spec_friendly`
+
+| `shared.diff.algorithm`
+| `cfg.xml.diff.algorithm = :dom`
+
+| `formats.xml.diff.context_lines`
+| `cfg.xml.diff.context_lines = 5`
+|===
+
+All `DiffConfig` and `MatchConfig` attributes documented in
+link:../reference/options-across-interfaces.adoc[Options Across Interfaces]
+are supported.
+
+== See also
+
+* link:environment-configuration/override-system.adoc[Override System] -- ENV variable priority
+* link:match-options/index.adoc[Match Options] -- match profile presets (`:strict`, `:spec_friendly`, etc.)
+* link:../guides/choosing-configuration.adoc[Choosing Configuration] -- decision guide