canon 0.1.22 → 0.2.0

data/docs/features/match-options/pretty-printed-fixtures.adoc

@@ -0,0 +1,270 @@
+---
+title: Pretty-Printed Fixture Support
+parent: Match Options
+nav_order: 5
+---
+= Pretty-printed fixture support
+:toc:
+:toclevels: 3
+
+== Problem statement
+
+A common pattern in Metanorma and similar XML-generating libraries is to compare
+a *compact* generated document (no inter-element whitespace) against a
+*hand-indented fixture* stored as an RSpec heredoc:
+
+[source,ruby]
+----
+expected_xml = <<~XML
+  <root>
+    <fmt-title>
+      <semx element="title" source="_">Foreword</semx>
+    </fmt-title>
+  </root>
+XML
+
+received_xml = "<root><fmt-title><semx element=\"title\" source=\"_\">Foreword</semx></fmt-title></root>"
+----
+
+When `fmt-title` and `semx` are classified as `:collapse` whitespace elements
+(their inline content matters but all whitespace forms are equivalent), the
+comparison _correctly_ detects whitespace differences: the fixture has text nodes
+`"\n  "` and `"\n"` inside `<fmt-title>` that are absent from the compact
+received document.
+
+This is the right behaviour in general.  However, for *fixture files that
+cannot be written as compact single-line strings* — because doing so would
+produce unreadable 1000-character lines — the indentation whitespace in the
+fixture is a necessary formatting artefact, not a meaningful content difference.
+
+=== Why the whitespace cannot simply be stripped
+
+The whitespace classification is intentionally asymmetric across elements:
+
+* Structural container elements (e.g. `<clause>`, `<foreword>`) are
+  `:strip` — their inter-element whitespace is already dropped in both
+  compact and indented forms.
+* Mixed-content elements (e.g. `<fmt-title>`, `<semx>`) are `:collapse` —
+  the _presence_ of a space between inline children is significant (it
+  represents a word-boundary), but its exact form is not.
+
+Stripping all whitespace from the fixture would destroy the signal inside
+mixed-content elements: `<p>See <em>note</em></p>` would become identical to
+`<p>See<em>note</em></p>`, hiding a real content difference.
+
+== Solution: asymmetric pretty-print flags
+
+Canon provides two match options and two display-preprocessing flags that
+instruct the relevant subsystem to treat whitespace-only text nodes that begin
+with `"\n"` as *structural indentation from the pretty-printer* and drop them
+from the comparison.  They operate independently so that only the
+actually-pretty-printed side is affected.
+
+`pretty_printed_expected`::
+  When `true`, whitespace-only text nodes that start with `"\n"` in
+  `:collapse`-classified elements of the **expected** (first / fixture)
+  document are dropped before comparison and before display.
+  Use this when fixture files are indented heredocs but received XML is compact.
+
+`pretty_printed_received`::
+  When `true`, the same treatment applies to the **received** (second / actual)
+  document.  Use this when the received output may be pretty-printed but the
+  fixture is compact.
+
+=== The heuristic explained
+
+The heuristic is:
+
+[source]
+----
+Whitespace-only text node starts with "\n"  →  structural indentation  →  drop
+Whitespace-only text node has no "\n"       →  inline content space    →  keep
+----
+
+The reasoning: compact Metanorma XML (and most programmatic XML serializers)
+never emit a bare `"\n"` immediately after a closing or opening tag inside a
+mixed-content element.  If a fixture heredoc contains such a `"\n"`, it was
+introduced by the human author formatting the fixture for readability — it is
+not part of the original document content.
+
+A _space_ not preceded by `"\n"` is treated as real content: in
+`<p>See <em>note</em></p>`, the text node `"See "` starts with `"S"`, so its
+trailing space is kept and normalized to a single `░` symbol in the display.
+
+NOTE: This heuristic is only activated for `:collapse` elements.  `:preserve`
+elements always preserve every whitespace character regardless of these flags.
+`:strip` elements already drop all whitespace and are unaffected.
+
+== Configuration
+
+=== Comparison (equivalence detection)
+
+Pass `pretty_printed_expected` or `pretty_printed_received` inside the `match:`
+hash of `Canon::Comparison.equivalent?` or the RSpec `be_xml_equivalent_to`
+matcher:
+
+[source,ruby]
+----
+# One-off: fixture is indented, received is compact
+result = Canon::Comparison.equivalent?(
+  fixture_xml,
+  received_xml,
+  match: {
+    collapse_whitespace_elements: %w[fmt-title semx],
+    pretty_printed_expected: true,
+  }
+)
+
+# RSpec global config in spec_helper.rb
+Canon::Config.configure do |cfg|
+  cfg.xml.match.options = {
+    collapse_whitespace_elements: %w[fmt-title semx],
+    pretty_printed_expected: true,
+  }
+end
+----
+
+=== Display preprocessing (`:normalize_pretty_print`)
+
+When using `display_preprocessing: :normalize_pretty_print`, set the
+corresponding diff-config flags so that the display side also strips structural
+indentation from only the flagged side:
+
+[source,ruby]
+----
+Canon::Config.configure do |cfg|
+  cfg.xml.diff.display_preprocessing    = :normalize_pretty_print
+  cfg.xml.diff.collapse_whitespace_elements = %w[fmt-title semx]
+
+  # Drop structural indentation from the indented fixture side only
+  cfg.xml.diff.pretty_printed_expected  = true
+  cfg.xml.diff.pretty_printed_received  = false   # compact received is unchanged
+end
+----
+
+=== Environment variables
+
+[source,bash]
+----
+export CANON_XML_DIFF_PRETTY_PRINTED_EXPECTED=true
+export CANON_XML_DIFF_PRETTY_PRINTED_RECEIVED=false
+----
+
+== Behaviour by whitespace class
+
+[cols="1,3,3,3"]
+|===
+|Element class |`pretty_printed_expected: false` (default) |`pretty_printed_expected: true`
+|Note
+
+|`:strip`
+|All inter-element whitespace dropped (both sides)
+|Same — no change
+|Already dropped; flag has no effect
+
+|`:collapse`
+|`"\n  "` nodes kept; compact vs. indented comparison detects difference
+|`"\n"`-starting nodes dropped from expected; compact vs. indented now equivalent
+|Inline content spaces (`" "` without `"\n"`) are always kept
+
+|`:preserve`
+|Every whitespace character compared verbatim
+|Same — no change
+|`:preserve` always preserves all whitespace regardless of flag
+
+|===
+
+== Example walkthrough
+
+=== Fixture (hand-indented heredoc)
+
+[source,xml]
+----
+<root>
+  <clause>
+    <fmt-title>
+      <semx element="title" source="_">Foreword</semx>
+    </fmt-title>
+  </clause>
+</root>
+----
+
+Text nodes inside `<fmt-title>` after Nokogiri parsing:
+
+* `"\n      "` between `<fmt-title>` open tag and `<semx>` — whitespace-only, starts with `"\n"`
+* `"\n    "` between `</semx>` and `</fmt-title>` — whitespace-only, starts with `"\n"`
+
+=== Received (compact Metanorma output)
+
+[source,xml]
+----
+<root><clause><fmt-title><semx element="title" source="_">Foreword</semx></fmt-title></clause></root>
+----
+
+No whitespace nodes inside `<fmt-title>`.
+
+=== Without `pretty_printed_expected: true`
+
+`clause` is `:strip`, so its inter-element whitespace is dropped.
+`fmt-title` and `semx` are `:collapse`, so their whitespace nodes are kept.
+
+The comparison finds two extra whitespace nodes in the expected side →
+**not equivalent**.
+
+=== With `pretty_printed_expected: true`
+
+The `"\n"`-starting nodes inside `:collapse` elements are dropped from the
+expected side before comparison.  The expected side now matches the compact
+received side → **equivalent**.
+
+== Interaction with `:pretty_diff` mode
+
+`:pretty_diff` mode applies `display_preprocessing` to both documents before
+running a text-LCS diff on the resulting lines.  When
+`pretty_printed_expected: true` is set on the formatter, `XmlNormalized` is
+instantiated with `pretty_printed: true` for the expected-side printer only.
+This drops the `"\n"`-starting whitespace visualization from the expected
+side's serialized lines, so the LCS diff sees identical lines for purely
+structural indentation differences.
+
+[source,ruby]
+----
+Canon::DiffFormatter.new(
+  mode: :pretty_diff,
+  display_preprocessing: :normalize_pretty_print,
+  collapse_whitespace_elements: %w[fmt-title semx],
+  pretty_printed_expected: true,   # strip structural \n nodes from fixture side
+  pretty_printed_received: false,  # compact received side is unchanged
+)
+----
+
+== Relation to deprecated `normalize_pretty_print_ignore_structural_newlines`
+
+The deprecated flag `normalize_pretty_print_ignore_structural_newlines` applied
+the newline-stripping heuristic to **both** sides simultaneously and without
+regard to whitespace classification.
+
+The new `pretty_printed_expected` / `pretty_printed_received` flags replace it
+with a more granular design:
+
+[cols="3,3"]
+|===
+|Old flag |New equivalent
+
+|`normalize_pretty_print_ignore_structural_newlines: true`
+|`pretty_printed_expected: true, pretty_printed_received: true`
+(plus `collapse_whitespace_elements:` to restrict to the right elements)
+|===
+
+The old flag is deprecated and still emits a warning; use the new flags for all
+new code.
+
+== See also
+
+* link:../../features/diff-formatting/display-preprocessing.adoc[Display preprocessing]
+  — the `display_preprocessing` option and `XmlNormalized` serializer
+* link:index.adoc[Match options overview] — whitespace sensitivity classification
+* link:../../reference/options-across-interfaces.adoc[Options across interfaces]
+  — cross-interface reference table
+* link:../../reference/environment-variables.adoc[Environment variables]
+  — `CANON_XML_DIFF_PRETTY_PRINTED_EXPECTED`, `CANON_XML_DIFF_PRETTY_PRINTED_RECEIVED`

data/docs/guides/choosing-configuration.adoc

@@ -679,8 +679,30 @@ When changing configuration:
 - [ ] Test with sample documents
 - [ ] Update documentation
 
+== Using Configuration Profiles
+
+If you use the same configuration across multiple gems or projects,
+consider using a **configuration profile** instead of repeating settings.
+A single line replaces dozens of configuration calls:
+
+[source,ruby]
+----
+# Instead of 60+ lines of per-format settings:
+Canon::Config.instance.profile = :metanorma
+
+# Or load a custom profile from a local YAML file:
+Canon::Config.instance.profile = "config/my_canon_profile.yml"
+----
+
+Profiles bundle all layers (preprocessing, match profile, diff settings,
+whitespace element lists) into a named preset defined in YAML.
+Custom file profiles can inherit from built-in profiles.
+
+See link:../features/configuration-profiles.adoc[Configuration Profiles] for full documentation.
+
 == See Also
 
+* link:../features/configuration-profiles.adoc[Configuration Profiles] - Named config presets
 * link:../understanding/comparison-pipeline.adoc[Comparison Pipeline] - Understanding the 4 layers
 * link:../understanding/algorithms/[Algorithms] - Detailed algorithm documentation
 * link:../features/match-options/algorithm-specific-behavior.adoc[Algorithm-Specific Behavior] - How algorithms differ

data/docs/reference/environment-variables.adoc

@@ -86,9 +86,129 @@ export CANON_JSON_FORMAT_PREPROCESSING=normalize
 |`CANON_MODE`
 |symbol
 |`:by_line`
-|Diff output mode: `by_line` or `by_object`
+|Diff output mode: `by_line`, `by_object`, or `rspec`
 |All formats
 
+|`CANON_DISPLAY_PREPROCESSING`
+|symbol
+|`:none`
+|How documents are normalized _for display_ before the line diff: `none`, `pretty_print`, `c14n`. Format-specific: `CANON_{FORMAT}_DIFF_DISPLAY_PREPROCESSING`
+|All formats
+
+|`CANON_PRETTY_PRINTER_INDENT`
+|integer
+|`2`
+|Indentation depth used by the pretty-printer when `display_preprocessing: :pretty_print`. Format-specific: `CANON_{FORMAT}_DIFF_PRETTY_PRINTER_INDENT`
+|All formats (display only)
+
+|`CANON_PRETTY_PRINTER_INDENT_TYPE`
+|symbol
+|`:space`
+|Indentation character for the pretty-printer: `space` or `tab`. Format-specific: `CANON_{FORMAT}_DIFF_PRETTY_PRINTER_INDENT_TYPE`
+|All formats (display only)
+
+|`CANON_XML_DIFF_COLLAPSE_WHITESPACE_ELEMENTS`
+|string array
+|`[]`
+|Comma-separated list of XML element names whose inter-element whitespace is *presence-significant but form-insensitive*: both `" "` and `"\n  "` collapse to a single `░`.  Suitable for inline mixed-content elements such as `<p>`, `<li>`, `<td>`.  Only applies when `display_preprocessing: :normalize_pretty_print`.  Format-specific; no global form.
+|XML (display only)
+
+|`CANON_XML_DIFF_PRESERVE_WHITESPACE_ELEMENTS`
+|string array
+|`[]`
+|Comma-separated list of XML element names where every whitespace character is significant and visualized verbatim (`" "` → `░`, `"\n  "` → `↵░░`).  Suitable for preformatted elements such as `<pre>`, `<code>`.  Only applies when `display_preprocessing: :normalize_pretty_print`.  Format-specific; no global form.
+|XML (display only)
+
+|`CANON_XML_DIFF_STRIP_WHITESPACE_ELEMENTS`
+|string array
+|`[]`
+|Comma-separated list of XML element names where whitespace-only text nodes are stripped entirely.  Only applies when `display_preprocessing: :normalize_pretty_print`.  Format-specific; no global form.
+|XML (display only)
+
+|`CANON_XML_DIFF_PRETTY_PRINTED_EXPECTED`
+|boolean
+|`false`
+|When `true`, whitespace-only text nodes that start with `"\n"` inside `:collapse`-classified elements are dropped from the **expected (fixture)** document before it reaches the line diff.  Solves the asymmetric case where the expected side is a hand-indented heredoc fixture but the received side is compact programmatic XML.  Only applies when `display_preprocessing: :normalize_pretty_print`.  Format-specific; no global form.  See also link:../features/match-options/pretty-printed-fixtures.adoc[Pretty-printed fixture support].
+|XML (display only)
+
+|`CANON_XML_DIFF_PRETTY_PRINTED_RECEIVED`
+|boolean
+|`false`
+|Same as `CANON_XML_DIFF_PRETTY_PRINTED_EXPECTED` but applied to the **received (actual)** document.  Useful when the received output may be pretty-printed but the fixture is compact.  Format-specific; no global form.
+|XML (display only)
+
+|`CANON_XML_DIFF_PRETTY_PRINTER_SORT_ATTRIBUTES`
+|boolean
+|`false`
+|When `true`, attributes on each element are sorted by namespace URI then local name in the pretty-printed display.  Eliminates spurious diff lines caused by differing attribute order between expected and received XML.  Only applies when `display_preprocessing` is `:pretty_print` or `:normalize_pretty_print`.  Format-specific; no global form.
+|XML (display only)
+
+|`CANON_SHOW_RAW_INPUTS`
+|boolean
+|`false`
+|Show the raw (un-preprocessed) file contents of both sides before the diff output.  Equivalent to enabling both `CANON_SHOW_RAW_EXPECTED` and `CANON_SHOW_RAW_RECEIVED`.  Format-specific: `CANON_{FORMAT}_DIFF_SHOW_RAW_INPUTS`
+|All formats (display only)
+
+|`CANON_SHOW_RAW_EXPECTED`
+|boolean
+|`false`
+|Show only the EXPECTED (fixture) block in the raw-inputs section.  Has no effect unless `show_raw_inputs` or `verbose_diff` is also set.  Format-specific: `CANON_{FORMAT}_DIFF_SHOW_RAW_EXPECTED`
+|All formats (display only)
+
+|`CANON_SHOW_RAW_RECEIVED`
+|boolean
+|`false`
+|Show only the RECEIVED (actual) block in the raw-inputs section.  Format-specific: `CANON_{FORMAT}_DIFF_SHOW_RAW_RECEIVED`
+|All formats (display only)
+
+|`CANON_SHOW_PREPROCESSED_INPUTS`
+|boolean
+|`false`
+|Show the preprocessed (post-comparison-preprocessing) contents of both sides before the diff output.  Equivalent to enabling both `CANON_SHOW_PREPROCESSED_EXPECTED` and `CANON_SHOW_PREPROCESSED_RECEIVED`.  Format-specific: `CANON_{FORMAT}_DIFF_SHOW_PREPROCESSED_INPUTS`
+|All formats (display only)
+
+|`CANON_SHOW_PREPROCESSED_EXPECTED`
+|boolean
+|`false`
+|Show only the EXPECTED (fixture) block in the preprocessed-inputs section.  Has no effect unless `show_preprocessed_inputs` or `verbose_diff` is also set.  Format-specific: `CANON_{FORMAT}_DIFF_SHOW_PREPROCESSED_EXPECTED`
+|All formats (display only)
+
+|`CANON_SHOW_PREPROCESSED_RECEIVED`
+|boolean
+|`false`
+|Show only the RECEIVED (actual) block in the preprocessed-inputs section.  Format-specific: `CANON_{FORMAT}_DIFF_SHOW_PREPROCESSED_RECEIVED`
+|All formats (display only)
+
+|`CANON_SHOW_PRETTYPRINT_INPUTS`
+|boolean
+|`false`
+|Show a fixture-ready pretty-printed form of **both** original input sides before the diff output.  The output is formatted with one XML/HTML tag per line and proper indentation (using the configured `pretty_printer_indent` / `pretty_printer_indent_type`), but with **no character visualization** — whitespace appears as plain ASCII so the output can be copy-pasted directly into RSpec heredoc fixtures.  Unlike `show_preprocessed_inputs`, this always pretty-prints the original strings regardless of the `preprocessing` or `display_preprocessing` settings.  Equivalent to enabling both `CANON_SHOW_PRETTYPRINT_EXPECTED` and `CANON_SHOW_PRETTYPRINT_RECEIVED`.  Format-specific: `CANON_{FORMAT}_DIFF_SHOW_PRETTYPRINT_INPUTS`
+|All formats (display only)
+
+|`CANON_SHOW_PRETTYPRINT_EXPECTED`
+|boolean
+|`false`
+|Show only the EXPECTED (fixture) block in the fixture-ready pretty-printed section.  Use this to see the current fixture re-formatted for copy-pasting when the fixture is the side that needs updating.  Format-specific: `CANON_{FORMAT}_DIFF_SHOW_PRETTYPRINT_EXPECTED`
+|All formats (display only)
+
+|`CANON_SHOW_PRETTYPRINT_RECEIVED`
+|boolean
+|`false`
+|Show only the RECEIVED (actual) block in the fixture-ready pretty-printed section.  This is the most common fixture-update workflow: enable this option to get a copy-pasteable pretty-printed form of the generated output that can replace the old fixture heredoc.  Format-specific: `CANON_{FORMAT}_DIFF_SHOW_PRETTYPRINT_RECEIVED`
+|All formats (display only)
+
+|`CANON_COMPACT_SEMANTIC_REPORT`
+|boolean
+|`false`
+|Render element nodes in the Semantic Diff Report as compact inline XML (e.g. `<strong>Annex</strong>`) instead of the verbose `node_info` description string (e.g. `name: strong namespace_uri: …`).  Useful when reading Semantic Diff output in the terminal and wanting to see the actual XML markup rather than a textual node description.  See format-specific form `CANON_{FORMAT}_DIFF_COMPACT_SEMANTIC_REPORT`.
+|All formats (display only)
+
+|`CANON_CHARACTER_VISUALIZATION`
+|symbol
+|`true`
+|Replace invisible characters with visible Unicode symbols in diff output: `true`, `false`, or `content_only`. Format-specific: `CANON_{FORMAT}_DIFF_CHARACTER_VISUALIZATION`. Set to `false` to keep plain-text output.
+|All formats (display only)
+
 |`CANON_USE_COLOR`
 |boolean
 |`true`

data/docs/reference/options-across-interfaces.adoc

@@ -29,7 +29,7 @@ The following table shows how major Canon options are expressed in each interfac
 |===
 |Option |CLI Flag |Ruby API |RSpec Config |ENV Variable
 
-|Preprocessing
+|Comparison Preprocessing
 |`--preprocessing normalize`
 |`preprocessing: :normalize`
 |`config.canon.xml.preprocessing = :normalize`
@@ -38,6 +38,111 @@ The following table shows how major Canon options are expressed in each interfac
 
 Preprocessing values: `none`, `c14n`, `normalize`, `format`
 
+NOTE: This controls how documents are normalized _before comparison_ (equivalence detection). It is independent of display preprocessing, which controls how documents are formatted for the diff output.
+
+=== Layer 1b: Display Preprocessing Options
+
+Display preprocessing controls how documents are normalized _before the line diff is rendered_. This is independent of comparison preprocessing. Because both sides go through the same normalization, the resulting line diff shows only genuine content differences rather than formatting differences.
+
+[cols="2,2,3,3,3"]
+|===
+|Option |CLI Flag |Ruby API |RSpec Config |ENV Variable
+
+|Display Preprocessing
+|`--display-preprocessing pretty_print`
+|`display_preprocessing: :pretty_print`
+|`cfg.xml.diff.display_preprocessing = :pretty_print`
+|`CANON_XML_DIFF_DISPLAY_PREPROCESSING=pretty_print`
+
+|Pretty-printer Indent
+|N/A
+|N/A (config only)
+|`cfg.xml.diff.pretty_printer.indent = 2`
+|`CANON_XML_DIFF_PRETTY_PRINTER_INDENT=2`
+
+|Pretty-printer Indent Type
+|N/A
+|N/A (config only)
+|`cfg.xml.diff.pretty_printer.indent_type = :space`
+|`CANON_XML_DIFF_PRETTY_PRINTER_INDENT_TYPE=space`
+
+|Collapse Whitespace Elements
+|N/A
+|N/A (config only)
+|`cfg.xml.match.collapse_whitespace_elements = %w[p li td th]`
+|`CANON_XML_MATCH_COLLAPSE_WHITESPACE_ELEMENTS=p,li,td,th`
+
+|Preserve Whitespace Elements
+|N/A
+|N/A (config only)
+|`cfg.xml.match.preserve_whitespace_elements = %w[pre code]`
+|`CANON_XML_MATCH_PRESERVE_WHITESPACE_ELEMENTS=pre,code`
+
+|Pretty-printed Expected
+|N/A
+|`match: { pretty_printed_expected: true }`
+|`cfg.xml.diff.pretty_printed_expected = true`
+|`CANON_XML_DIFF_PRETTY_PRINTED_EXPECTED=true`
+
+|Pretty-printed Received
+|N/A
+|`match: { pretty_printed_received: true }`
+|`cfg.xml.diff.pretty_printed_received = true`
+|`CANON_XML_DIFF_PRETTY_PRINTED_RECEIVED=true`
+
+|Sort Attributes (pretty printer)
+|N/A
+|N/A (config only)
+|`cfg.xml.diff.pretty_printer_sort_attributes = true`
+|`CANON_XML_DIFF_PRETTY_PRINTER_SORT_ATTRIBUTES=true`
+
+|Compact Semantic Report
+|N/A
+|N/A (config only)
+|`cfg.xml.diff.compact_semantic_report = true`
+|`CANON_XML_DIFF_COMPACT_SEMANTIC_REPORT=true`
+
+|Expand Difference
+|N/A
+|N/A (config only)
+|`cfg.xml.diff.expand_difference = true`
+|`CANON_XML_DIFF_EXPAND_DIFFERENCE=true`
+|===
+
+Display preprocessing values: `none` (default), `pretty_print`, `normalize_pretty_print`, `c14n`
+
+* `:none` — documents are used as-is for the line diff (existing behaviour)
+* `:pretty_print` — both documents are run through a format-specific pretty-printer before the line diff: `Canon::PrettyPrinter::Xml` for XML (one tag per line, consistent indentation); `Canon::PrettyPrinter::Html` (Nokogiri HTML5 serializer) for HTML. Recommended for XML and HTML RSpec tests.
+* `:normalize_pretty_print` — like `:pretty_print` but uses `Canon::PrettyPrinter::XmlNormalized`, which guarantees one line per XML node even for mixed-content elements (those containing both text and child elements). Recommended when XML contains inline markup (Metanorma, DocBook). Use `collapse_whitespace_elements` or `preserve_whitespace_elements` to control per-element whitespace visualization.
+* `:c14n` — both documents are run through canonical normalization before the line diff. For XML: canonical XML (C14N, attribute-order sorting). For HTML: Nokogiri HTML5 serialization (normalizes attribute order and whitespace).
+
+NOTE: Pretty-printer indent options only apply when `display_preprocessing` is `:pretty_print` or `:normalize_pretty_print`.
+
+NOTE: `compact_semantic_report` controls the representation of XML element nodes in the *Semantic Diff Report* section (the structured summary that appears above the line diff).  When `false` (default), element nodes are described with their `node_info` string (e.g. `name: strong namespace_uri: …`), which is unambiguous but verbose.  When `true`, element nodes are serialized as compact inline XML (e.g. `<strong>Annex A</strong>`), which is much easier to read at a glance.  Plain text nodes (leaf text content) are not affected — they always display their decoded string value.
+
+=== Layer 1c: Character Visualization
+
+Character visualization controls whether invisible characters (spaces, tabs, non-breaking spaces, etc.) are replaced with visible Unicode symbols in diff output.
+
+[cols="2,2,3,3,3"]
+|===
+|Option |CLI Flag |Ruby API |RSpec Config |ENV Variable
+
+|Character Visualization
+|N/A
+|`character_visualization: true`
+|`cfg.xml.diff.character_visualization = false`
+|`CANON_XML_DIFF_CHARACTER_VISUALIZATION=false`
+|===
+
+Character visualization values:
+
+* `true` — (default) the full default visualization map is applied; spaces appear as `░`, tabs as `⇥`, non-breaking spaces as `␣`, etc.
+* `false` — visualization is disabled; all characters appear as plain text.
+* `:content_only` — reserved for future use; currently behaves as `true`. Future intent: apply visualization only to text-node content, leaving structural indentation whitespace plain.
+
+NOTE: Setting `character_visualization: false` is useful when copying diff output from a failure message, or when downstream tooling cannot handle Unicode symbol substitutions.
+
 === Layer 2: Algorithm Selection
 
 [cols="2,2,3,3,3"]
@@ -58,7 +163,7 @@ Preprocessing values: `none`, `c14n`, `normalize`, `format`
 |===
 
 Algorithm values: `dom`, `semantic` +
-Diff mode values: `by_line`, `by_object`
+Diff mode values: `by_line`, `by_object`, `pretty_diff`
 
 === Layer 3: Match Options
 
@@ -195,6 +300,81 @@ Values: `strict`, `ignore`
 |`CANON_GROUPING_LINES=15`
 |===
 
+=== Debug Input Display Options
+
+These options control whether Canon dumps the raw or preprocessed document content to the terminal alongside the diff.  They are useful for debugging comparisons — e.g. inspecting what the received output actually looks like before filing an issue.
+
+[cols="2,2,3,3,3"]
+|===
+|Option |CLI Flag |Ruby API |RSpec Config |ENV Variable
+
+|Show Raw Inputs (both)
+|`--show-raw-inputs`
+|N/A (config only)
+|`cfg.xml.diff.show_raw_inputs = true`
+|`CANON_XML_DIFF_SHOW_RAW_INPUTS=true`
+
+|Show Raw Expected only
+|N/A
+|N/A (config only)
+|`cfg.xml.diff.show_raw_expected = true`
+|`CANON_XML_DIFF_SHOW_RAW_EXPECTED=true`
+
+|Show Raw Received only
+|N/A
+|N/A (config only)
+|`cfg.xml.diff.show_raw_received = true`
+|`CANON_XML_DIFF_SHOW_RAW_RECEIVED=true`
+
+|Show Preprocessed Inputs (both)
+|`--show-preprocessed-inputs`
+|N/A (config only)
+|`cfg.xml.diff.show_preprocessed_inputs = true`
+|`CANON_XML_DIFF_SHOW_PREPROCESSED_INPUTS=true`
+
+|Show Preprocessed Expected only
+|`--show-preprocessed-expected`
+|N/A (config only)
+|`cfg.xml.diff.show_preprocessed_expected = true`
+|`CANON_XML_DIFF_SHOW_PREPROCESSED_EXPECTED=true`
+
+|Show Preprocessed Received only
+|`--show-preprocessed-received`
+|N/A (config only)
+|`cfg.xml.diff.show_preprocessed_received = true`
+|`CANON_XML_DIFF_SHOW_PREPROCESSED_RECEIVED=true`
+
+|Show Pretty-printed Inputs (both)
+|`--show-prettyprint-inputs`
+|N/A (config only)
+|`cfg.xml.diff.show_prettyprint_inputs = true`
+|`CANON_XML_DIFF_SHOW_PRETTYPRINT_INPUTS=true`
+
+|Show Pretty-printed Expected only
+|`--show-prettyprint-expected`
+|N/A (config only)
+|`cfg.xml.diff.show_prettyprint_expected = true`
+|`CANON_XML_DIFF_SHOW_PRETTYPRINT_EXPECTED=true`
+
+|Show Pretty-printed Received only
+|`--show-prettyprint-received`
+|N/A (config only)
+|`cfg.xml.diff.show_prettyprint_received = true`
+|`CANON_XML_DIFF_SHOW_PRETTYPRINT_RECEIVED=true`
+
+|Show Line-Numbered Inputs
+|`--show-line-numbered-inputs`
+|N/A (config only)
+|`cfg.xml.diff.show_line_numbered_inputs = true`
+|`CANON_XML_DIFF_SHOW_LINE_NUMBERED_INPUTS=true`
+|===
+
+NOTE: `show_raw_inputs`, `show_preprocessed_inputs`, and `show_prettyprint_inputs` are convenience shorthands for enabling both sides of their respective section simultaneously.  Use the per-side variants (`*_expected` / `*_received`) when you only want to display one side — e.g. suppress the (long) expected fixture and show only what was generated.
+
+NOTE: The *pretty-printed* section (`show_prettyprint_*`) differs from the *preprocessed* section (`show_preprocessed_*`) in two ways: (1) it always pretty-prints the **original** strings using `PrettyPrinter::Xml`/`Html`, independently of any `preprocessing` or `display_preprocessing` setting; and (2) it outputs **plain ASCII** with no character visualization (spaces remain spaces), making the output suitable for direct copy-paste into RSpec heredoc fixtures.
+
+NOTE: `verbose_diff` enables the raw, preprocessed, and line-numbered debug sections simultaneously.  It does **not** enable the pretty-printed section, which is a fixture-oriented feature independent of debugging verbosity.
+
 === Size Limit Options
 
 [cols="2,2,3,3,3"]

data/lib/canon/cli.rb

@@ -238,6 +238,26 @@ module Canon
                   type: :boolean,
                   default: false,
                   desc: "Show preprocessed contents (what was actually compared)"
+    method_option :show_preprocessed_expected,
+                  type: :boolean,
+                  default: false,
+                  desc: "Show only the EXPECTED (fixture) block in the preprocessed-inputs section"
+    method_option :show_preprocessed_received,
+                  type: :boolean,
+                  default: false,
+                  desc: "Show only the RECEIVED (actual) block in the preprocessed-inputs section"
+    method_option :show_prettyprint_inputs,
+                  type: :boolean,
+                  default: false,
+                  desc: "Show fixture-ready pretty-printed form of both inputs (no whitespace visualization)"
+    method_option :show_prettyprint_expected,
+                  type: :boolean,
+                  default: false,
+                  desc: "Show only the EXPECTED block in the fixture-ready pretty-printed section"
+    method_option :show_prettyprint_received,
+                  type: :boolean,
+                  default: false,
+                  desc: "Show only the RECEIVED block in the fixture-ready pretty-printed section"
     method_option :show_line_numbered_inputs,
                   type: :boolean,
                   default: false,