canon 0.1.8 → 0.1.10

data/old-docs/DIFF_PARAMETERS.adoc

@@ -1,261 +0,0 @@
-== Diff renderer
-
-=== General
-
-A diff renderer is responsible for taking a diff report and producing a
-human-readable representation of the differences between two text files.
-
-Canon provides a built-in diff renderer that produces a colored
-diff output, highlighting the differences between the two files,
-in either a by-object or by-line format.
-
-=== Concepts
-
-==== Diff report
-
-A diff report is a structured representation of the complete differences between
-two text files. It is composed of multiple diff contexts.
-
-A diff report serves as the input to a diff renderer, which processes the report
-to generate a human-readable diff output.
-
-A diff report is generated by a comparison engine that analyzes the two text
-files and identifies the differences between them.
-
-==== Diff context
-
-A diff context is a representation of a group of diff blocks with surrounding
-grouping lines.
-
-When the amount of grouping lines is set to 0, each diff block is treated as its
-own context.
-
-When the amount of grouping lines is greater than 0, multiple diff blocks that are close to each other can be grouped together into a single context.
-
-==== Diff block
-
-A diff block is a representation of a contiguous block of changes.
-
-In typical line-based diffing, a diff block consists of a run of consecutive lines that have been added, removed, or modified.
-
-In Canon, which uses semantic diffing, a diff block is a representation of a
-contiguous block of changes, which may be a many-to-many mapping of changes
-lines depending on the nature of the change.
-
-
-=== Parameters
-
-Canon diff renderers support the following parameters:
-
-==== Parameters
-
-The following table shows all available diff formatting parameters and their
-availability across interfaces:
-
-[cols="1,1,1,1,2,1"]
-|===
-|Parameter |RSpec |CLI |Ruby API |Description |Default
-
-|`use_color`
-|✓
-|✓
-|✓
-|Enable/disable colored output
-|`true`
-
-|`diff_mode`
-|✓
-|✓
-|✓
-|Comparison mode: `:by_object` or `:by_line`
-|`:by_line` (RSpec), `:by_object` (XML/JSON/YAML)
-
-|`context_lines`
-|✓
-|✓
-|✓
-|Number of unchanged lines to show around each change
-|`3`
-
-|`diff_grouping_lines`
-|✓
-|✓
-|✓
-|Maximum line distance to group separate diffs into context blocks
-|`10`
-|===
-
-==== Use color
-
-`use_color: <boolean>` default: `true`
-
-Specifies whether to produce colored diff output using ANSI color codes.
-
-When `use_color` is `true`, the diff output includes ANSI color codes to
-enhance readability by visually distinguishing different types of changes.
-
-* Type: Boolean
-* Default: `true`
-* Colors used:
-** Red: Deletions/removed content
-** Green: Additions/inserted content
-** Yellow: Modified content
-** Cyan: Element names and structure
-
-When `use_color` is `false`:
-
-* Line numbers and pipes are plain text
-* Whitespace is not visualized (remains invisible)
-* Unicode legend is still shown (but without color)
-* Content changes are shown without color highlighting
-
-
-**Purpose**: Improve readability by distinguishing structural elements from
-content changes.
-
-When color mode is enabled (`use_color: true`), the diff formatter uses a
-consistent color scheme:
-
-* **Yellow**: Line numbers and pipe separators
-* **Red**: Deletion markers (`-`) and removed content
-* **Green**: Addition markers (`+`) and inserted content
-* **Default terminal color**: Unchanged context lines (no ANSI codes applied)
-
-This color scheme helps differentiate between:
-
-* The diff structure (line numbers, pipes)
-* Content that was removed (red)
-* Content that was added (green)
-* Content that stayed the same (your terminal's default color)
-
-.Example colored diff output
-[example]
-In a colored terminal, a typical diff line appears as:
-
-[source]
-----
-   5|   5 |   <p>First paragraph</p>     # Context line (yellow numbers/pipes, default text)
-   6|     -|   <old>Text</old>            # Deletion (yellow numbers/pipes, red marker/content)
-    |   6+|   <new>Text</new>             # Addition (yellow numbers/pipes, green marker/content)
-----
-
-Where:
-
-* Line numbers (`5`, `6`) are in yellow
-* Pipe separators (`|`) are in yellow
-* Markers (`-`, `+`) are in red/green respectively
-* Changed content is highlighted in red (deletions) or green (additions)
-* Unchanged content uses your terminal's default color (no forced white/black)
-
-**Why this matters**: When running tests with RSpec, the framework initially sets
-output to red. Canon's diff formatter explicitly resets colors to prevent RSpec's
-red from bleeding into the diff output, ensuring consistent and readable diffs.
-
-
-==== Diff mode
-
-`diff_mode: <string>` default: `by_line`
-
-
-==== Context lines
-
-`context_lines: <number>` default: `3`
-
-Specifies the number of context lines before and after the diff block to show.
-
-Usage:
-
-[source,ruby]
-----
-renderer = Canon::DiffFormatter::Renderer.new(context_lines: 5)
-diff_output = renderer.render(diff_report)
-----
-
-.Example of XML line-by-line diff with context lines set to 3
-[example]
-====
-There are 3 context lines before and after the diff block:
-
-[source]
-----
-Line-by-line diff (XML mode):
-Character Visualization Legend:
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Whitespace:
-'␣': U+00A0 (' ') NO-Break-Space
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-29|  29  | <eref bibitemid="_" citeas="ISO 639-2" id="_" type="inline">
-30|  30  | </eref>
-31|  31  | <semx element="eref" source="_">
-32|    - | <fmt-eref░bibitemid="_"░citeas="ISO░639-2"░type="inline">ISO\u00a0639-2</fmt-eref>
-  |  32+ | <fmt-eref░bibitemid="_"░citeas="ISO░639-2"░type="inline">ISO␣639-2</fmt-eref>
-33|  33  | </semx>
-34|  34  | </p>
-35|  35  | </clause>
-----
-====
-
-==== Grouping lines
-
-`diff_grouping_lines: <number>` default: `0`
-
-Specifies the number of grouping lines to coalesce nearby diff blocks into a
-single context.
-
-The algorithm groups diff blocks as long as the distance between the previous
-block's end and the next block's start is less than or equal to the grouping
-lines setting.
-
-The default value of `0` means that each diff block is treated as its own
-context.
-
-When set to `5`, for example, any two diff blocks that are within 5 lines of
-each other will be grouped together into a single context.
-
-.Example of XML line-by-line diff with grouping lines set to 10
-[example]
-====
-Here, multiple diff blocks are grouped together into a single context because
-they are within 10 lines of each other.
-
-[source]
-----
-Line-by-line diff (XML mode):
-Character Visualization Legend:
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Whitespace:
-  '␣': U+00A0 (' ') NO-Break-Space
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-  22|  22  | <span class="fmt-element-name">Figure</span>
-  23|  23  | <semx element="autonum" source="B1">1</semx>
-  24|  24  | </span>
-  25|    - | <span░class="fmt-caption-delim">\u00a0—░</span>
-    |  25+ | <span░class="fmt-caption-delim">␣—░</span>
-  26|  26  | <semx element="name" source="_">First</semx>
-  27|  27  | </fmt-name>
-  28|  28  | <fmt-xref-label>
-
-  57|  57  | <span class="fmt-element-name">Figure</span>
-  58|  58  | <semx element="autonum" source="B2">2</semx>
-  59|  59  | </span>
-  60|    - | <span░class="fmt-caption-delim">\u00a0—░</span>
-    |  60+ | <span░class="fmt-caption-delim">␣—░</span>
-  61|  61  | <semx element="name" source="_">Second</semx>
-  62|  62  | </fmt-name>
-  63|  63  | <fmt-xref-label>
-
-100| 100  | <span class="fmt-element-name">Figure</span>
-101| 101  | <semx element="autonum" source="B3">3</semx>
-102| 102  | </span>
-103|    - | <span░class="fmt-caption-delim">\u00a0—░</span>
-    | 103+ | <span░class="fmt-caption-delim">␣—░</span>
-104| 104  | <semx element="name" source="_">Third</semx>
-105| 105  | </fmt-name>
-106| 106  | <fmt-xref-label>
-----
-====
-