svg_conform 0.1.0

data/README.adoc

@@ -0,0 +1,1384 @@
+= SvgConform: Ruby library for validating and fixing SVG files
+:toc: left
+:toclevels: 3
+:sectlinks:
+:sectanchors:
+:source-highlighter: rouge
+
+== Purpose
+
+SvgConform is an SVG conformance processor that validates SVG documents against
+defined SVG profiles, and supports automatic remediation of profile requirement
+violations when possible.
+
+SvgConform is designed to ensure SVG files meet specific requirements for
+different use cases, such as those required in:
+
+* Metanorma documents
+* PDF and PDF/A compliance
+* IETF XMLRFC documents (RFC 7996)
+
+SvgConform is distributed as a Ruby gem.
+
+
+== Features
+
+* **Profile-based validation**: Validate SVG files against predefined or custom profiles
+* **Remediation**: Automatically fix common SVG conformance issues
+* **Extensible architecture**: Easy to add new rules and profiles
+* **Command-line interface**: Validate and fix files from the command line
+* **Ruby API**: Integrate validation into Ruby applications
+* **Multiple report output formats**: Text and JSON output formats
+* **100% SVGCheck compatibility**: Perfect error report matching with Python svgcheck tool
+* **Configurable RDF metadata support**: Choose strict or permissive RDF/Dublin Core handling
+* **Generic namespace handling**: Configuration-driven foreign namespace validation
+
+
+== Concepts
+
+=== General
+
+SvgConform is built upon a set of core concepts that define its architecture and
+functionality.
+
+
+=== SVG document
+
+An SVG document is a file that contains Scalable Vector Graphics (SVG) content.
+
+In SvgConform, an SVG document is represented by the `SvgConform::Document` class,
+which wraps the Moxml XML document and provides SVG-specific functionality.
+
+
+=== SVG profile
+
+An SVG profile is a defined set of requirements that an SVG document must meet.
+
+These requirements represent concerns that go beyond the SVG standards, such as
+accessibility or stylistic concerns.
+
+In SvgConform, a `Profile` object is a collection of requirements and
+remediations that define a specific SVG conformance standard.
+
+Each `Profile` object consists of:
+
+* `Requirement` objects: Validation checks that determine if an SVG document
+conforms to the profile
+
+* `Remediation` objects: Automatic fixes that can be applied when requirements
+fail
+
+* `Configuration` objects: Profile-specific settings and parameters
+
+
+Conformance to an SVG profile is a measure of the degree to which an SVG
+document meets the requirements of a specific profile.
+
+In SvgConform, SVG conformance is determined by whether an SVG document passes
+all the requirements defined in the profile.
+
+
+=== SVG requirement
+
+An SVG requirement is a specific condition or set of conditions that an SVG
+document must meet.
+
+In SvgConform, a `Requirement` object encapsulates the logic to check for a
+specific requirement.
+
+Each `Requirement` object is designed to be modular and focuses on a single
+concern, such as color usage, font family restrictions, or structural validity.
+
+
+=== SVG remediation action
+
+An SVG remediation action is an automatic fix or adjustment applied to an SVG
+document to resolve one or more SVG requirement failures.
+
+A remediation action may imply a lossless or lossy change.
+
+In SvgConform, a `Remediation` object encapsulates the logic to perform a
+specific remediation action.
+
+Each `Remediation` object targets one or more specific requirements through a
+mapping system.
+
+
+=== Defining profiles with configuration
+
+Requirements and remediations can be configured with specific parameters to
+customize their behavior.
+
+In SvgConform, `Requirement` and `Remediation` objects are customizable
+executable components that can be tailored to specific use cases.
+
+These parameters can be set in the profile YAML configuration to influence how
+requirements and remediations operate.
+
+In combination, it allows for flexible definition and authoring of new
+deterministic SVG profiles, with the ability to enforce specific requirements
+and remediation strategies.
+
+Each remediation action can be linked to a particular requirement to indicate
+their relationship, defined in the profile.
+
+
+=== Reporting
+
+SvgConform provides detailed reporting on SVG conformance issues.
+
+* Validation results: Summary of passed and failed checks
+* Report formats: The resulting validation report can be exported
+  in machine-readable formats, including JSON and YAML
+* Error messages: Descriptions of specific conformance issues
+
+
+=== Compatibility with other tools
+
+SvgConform aims to deliver accurate results for compatibility with existing SVG
+profile conformance tools.
+
+See <<external_compliance>> for details.
+
+
+
+== Usage
+
+=== Installation
+
+Add this line to your application's Gemfile:
+
+[source,ruby]
+----
+gem 'svg_conform'
+----
+
+And then execute:
+
+[source,bash]
+----
+$ bundle install
+----
+
+Or install it yourself as:
+
+[source,bash]
+----
+$ gem install svg_conform
+----
+
+
+=== Command line usage
+
+Details and examples of command line usage can be found in
+<<command_line_interface>>.
+
+List available profiles:
+
+[source,bash]
+----
+$ svg_conform profiles
+----
+
+Check/validate an SVG file against a profile:
+
+[source,bash]
+----
+$ svg_conform check file.svg --profile=metanorma
+----
+
+Check and fix an SVG file to conform to a profile:
+
+[source,bash]
+----
+$ svg_conform check file.svg --profile=metanorma -f --fix-output=fixed.svg
+----
+
+Batch process a directory of SVG files:
+
+[source,bash]
+----
+$ svg_conform check --directory=images/ --profile=metanorma -f --output-dir=fixed/
+----
+
+
+=== Ruby API usage
+
+Details and examples of Ruby API usage can be found in
+<<ruby_api_reference>>.
+
+[source,ruby]
+----
+require 'svg_conform'
+
+# Load a profile and validate
+profile = SvgConform::Profile.load_from_file("config/profiles/svg_1_2_rfc.yml")
+document = SvgConform::Document.new(svg_content)
+result = profile.validate(document)
+
+puts "Valid: #{result.valid?}"
+puts "Errors: #{result.errors.count}"
+puts "Warnings: #{result.warnings.count}"
+
+# Apply remediations to fix issues
+if !result.valid? && profile.has_remediations?
+  engine = SvgConform::RemediationEngine.new(profile)
+  remediation_results = engine.apply_remediations(document, result)
+
+  puts "Applied #{remediation_results.length} remediations"
+  puts "Fixed SVG:"
+  puts document.to_xml
+end
+----
+
+
+
+== Core components
+
+=== Architecture
+
+The SvgConform architecture is built around a modular design that separates
+concerns and allows for easy extension.
+
+
+[source]
+----
+╭────────────────────────────────────────────────────────────────╮
+│                        SvgConform                              │
+├────────────────────────────────────────────────────────────────┤
+│                                                                │
+│  ╭─────────────╮    ╭─────────────╮    ╭─────────────╮         │
+│  │     CLI     │    │  Ruby API   │    │   Profiles  │         │
+│  │             │    │             │    │   Registry  │         │
+│  ╰─────┬───────╯    ╰──────┬──────╯    ╰─────┬───────╯         │
+│        │                   │                 │                 │
+│        └───────────────────┼─────────────────┘                 │
+│                            │                                   │
+│  ╭─────────────────────────▼─────────────────────────╮         │
+│  │                     Validator                     │         │
+│  │ ╭─────────────╮  ╭─────────────╮  ╭─────────────╮ │         │
+│  │ │  Document   │  │ Validation  │  │ Remediation │ │         │
+│  │ │   Parser    │  │   Engine    │  │   Engine    │ │         │
+│  │ ╰─────────────╯  ╰─────────────╯  ╰─────────────╯ │         │
+│  ╰─────────────────────────┬─────────────────────────╯         │
+│                            │                                   │
+│  ╭─────────────────────────▼─────────────────────────╮         │
+│  │                  Profile System                   │         │
+│  │                                                   │         │
+│  │ ╭─────────────╮ ╭─────────────╮ ╭─────────────╮   │         │
+│  │ │ SVG 1.2 RFC │ │ Metanorma   │ │   Future    │   │         │
+│  │ │   Profile   │ │ SVG Profile │ │  Profiles   │   │         │
+│  │ │             │ │             │ │             │   │         │
+│  │ │ • svgcheck  │ │ • ID links  │ │ • Custom    │   │         │
+│  │ │ compatible  │ │ • No ext.   │ │   rules     │   │         │
+│  │ │ • Grayscale │ │   fonts     │ │ • Org       │   │         │
+│  │ │ • RFC 7996  │ │ • Font def. │ │   standards │   │         │
+│  │ ╰─────────────╯ ╰─────────────╯ ╰─────────────╯   │         │
+│  ╰─────────────────────────┬─────────────────────────╯         │
+│                            │                                   │
+│  ╭─────────────────────────▼─────────────────────────╮         │
+│  │        Requirements & Remediations Engine         │         │
+│  │ ╭─────────────╮  ╭─────────────╮  ╭─────────────╮ │         │
+│  │ │Requirements │  │Remediations │  │ Validation  │ │         │
+│  │ │   System    │  │   System    │  │   Results   │ │         │
+│  │ ╰─────────────╯  ╰─────────────╯  ╰─────────────╯ │         │
+│  ╰─────────────────────────┬─────────────────────────╯         │
+│                            │                                   │
+│  ╭─────────────────────────▼─────────────────────────╮         │
+│  │             svgcheck Compatibility                │         │
+│  │ ╭─────────────╮  ╭─────────────╮  ╭─────────────╮ │         │
+│  │ │ svgcheck    │  │    YAML     │  │   Report    │ │         │
+│  │ │   Parser    │  │   Mapping   │  │ Comparator  │ │         │
+│  │ ╰─────────────╯  ╰─────────────╯  ╰─────────────╯ │         │
+│  ╰─────────────────────────┬─────────────────────────╯         │
+│                            │                                   │
+│  ╭─────────────────────────▼─────────────────────────╮         │
+│  │                       Moxml                       │         │
+│  │                  (XML Processing)                 │         │
+│  ╰───────────────────────────────────────────────────╯         │
+│                                                                │
+╰────────────────────────────────────────────────────────────────╯
+----
+
+
+=== Profiles
+
+SvgConform includes predefined profiles that can be used out-of-the-box.
+Each profile is designed for different use cases and compliance standards.
+
+.Predefined SVG profiles included in SvgConform
+[cols="2,3,3,2", options="header"]
+|===
+|Profile |Use Case |Key Features |Documentation
+
+|`base`
+|Foundation profile
+|Basic validation, namespace checks, starting point for custom profiles.
+|link:docs/profiles.adoc#base-profile[Details]
+
+|`metanorma`
+|Metanorma SVG profile
+|Standard SVG for Metanorma documents. Valid HREFs and ID linking. No external
+fonts, images and CSS. No non-SVG elements or attributes.
+|link:docs/profiles.adoc#no-external-css-profile[Details]
+
+|`svg_1_2_rfc`
+|IETF RFC SVG 1.2 profile
+|RFC 7996/6949 compliant. Black/white color only, limited elements, generic
+fonts. Fully compatible with `svgcheck` outcomes.
+|link:docs/profiles.adoc#svg-1-2-rfc-profile[Details]
+
+|`svg_1_2_rfc_with_rdf`
+|IETF RFC SVG 1.2 profile with RDF metadata
+|Same as `svg_1_2_rfc`, but allows RDF/Dublin Core metadata from design tools.
+Supported by `svgcheck`.
+|link:docs/profiles.adoc#svg-1-2-rfc-with-rdf-profile[Details]
+
+|`no_external_css`
+|Self-contained SVG
+|No external references, security-focused, offline usage.
+|link:docs/profiles.adoc#no-external-css-profile[Details]
+
+|`lucid_fix`
+|Lucid cleanup
+|Remove Lucid-specific metadata, clean standard SVG output
+|link:docs/profiles.adoc#lucid-fix-profile[Details]
+|===
+
+For complete profile documentation, including inheritance, customization, RDF
+metadata support, and selection guides, see
+link:docs/profiles.adoc[SVG Profiles Documentation].
+
+For detailed information about configuring RDF metadata support in profiles, see
+link:docs/rdf_metadata_support.adoc[RDF Metadata Support Documentation].
+
+
+
+=== Requirements
+
+SvgConform includes different requirement checkers that validate various aspects
+of SVG documents.
+
+There are two main categories of requirements:
+
+* structural requirements: requirements set towards the XML structure and syntax of SVG documents
+* logical requirements: requirements set towards content and stylistic aspects of SVG documents
+
+.SvgConform supported requirement classes
+[cols="2,2,3", options="header"]
+|===
+|Type |Requirement |Description
+
+|Structural
+|`NamespaceRequirement`
+|Ensures proper SVG namespace declarations
+
+|Structural
+|`NamespaceAttributesRequirement`
+|Validates namespace attributes are from allowed namespaces
+
+|Structural
+|`AllowedElementsRequirement`
+|Restricts which SVG elements are permitted
+
+|Structural
+|`ViewboxRequiredRequirement`
+|Requires viewBox attributes on root elements
+
+|Logical
+|`ColorRestrictionsRequirement`
+|Enforces color usage restrictions (e.g., grayscale only)
+
+|Logical
+|`FontFamilyRequirement`
+|Controls font family usage and validates font specifications
+
+|Logical
+|`NoExternalCssRequirement`
+|Prevents external CSS references to ensure self-contained documents
+
+|Logical
+|`ForbiddenContentRequirement`
+|Prevents inclusion of forbidden elements and attributes
+
+|Logical
+|`IdReferenceRequirement`
+|Validates that ID references point to existing elements
+
+|Logical
+|`InvalidIdReferencesRequirement`
+|Detects and validates broken ID references in SVG documents
+
+|Logical
+|`LinkValidationRequirement`
+|Validates that links use only ASCII characters (IETF requirement)
+
+|Logical
+|`StyleRequirement`
+|Comprehensive CSS style validation including syntax and properties
+
+|Logical
+|`StylePromotionRequirement`
+|Detects style properties that should be promoted to SVG attributes
+|===
+
+
+
+=== Remediations
+
+Remediations are automatic fixing actions that can resolve requirement failures.
+Each remediation targets one or more specific requirements.
+
+SvgConform includes different remediation actions that can automatically fix
+SVG documents to resolve requirement violations.
+
+.SvgConform supported remediation classes
+[cols="2,2,3,2", options="header"]
+|===
+|Type |Remediation |Description |Targets
+
+|Content Conversion
+|`ColorRemediation`
+|Converts invalid colors to allowed alternatives using threshold-based conversion
+|<<color-restrictions-requirement,`ColorRestrictionsRequirement`>>
+
+|Content Conversion
+|`FontRemediation`
+|Maps font families to generic alternatives (serif, sans-serif, monospace)
+|<<font-family-requirement,`FontFamilyRequirement`>>
+
+|Element/Attribute Removal
+|`NamespaceRemediation`
+|Removes invalid namespace elements and cleans up namespace declarations
+|<<namespace-requirement,`NamespaceRequirement`>>
+
+|Element/Attribute Removal
+|`NamespaceAttributeRemediation`
+|Removes attributes from disallowed namespaces
+|<<namespace-attributes-requirement,`NamespaceAttributesRequirement`>>
+
+|Element/Attribute Removal
+|`NoExternalCssRemediation`
+|Removes external CSS references including @import and external stylesheets
+|<<no-external-css-requirement,`NoExternalCssRequirement`>>
+
+|Addition
+|`ViewboxRemediation`
+|Adds missing viewBox attributes to root SVG elements
+|<<viewbox-required-requirement,`ViewboxRequiredRequirement`>>
+
+|Style Processing
+|`StylePromotionRemediation`
+|Promotes CSS style properties to equivalent SVG attributes
+|<<style-promotion-requirement,`StylePromotionRequirement`>>
+
+|Reference Fixing
+|`InvalidIdReferencesRemediation`
+|Fixes or removes broken ID references and invalid href attributes
+|<<id-reference-requirement,`IdReferenceRequirement`>>, <<invalid-id-references-requirement,`InvalidIdReferencesRequirement`>>
+|===
+
+
+=== Requirement and remediation mapping
+
+Remediations are mapped to requirements using the `targets` configuration in
+profile YAML files.
+
+[source,yaml]
+----
+remediations:
+  - id: "fix_invalid_colors"
+    type: "ColorRemediationAction"
+    description: "Convert invalid colors to black or white"
+    targets: ["color_restrictions"]  # Maps to ColorRestrictionsRequirement
+----
+
+This mapping system allows:
+
+* **Targeted fixes**: Remediations only run when their target requirements fail
+* **Flexible configuration**: Multiple remediations can target the same requirement
+* **Conditional application**: Remediations can be enabled/disabled per profile
+
+
+
+=== Validation and remediation flow
+
+The following steps illustrates the data flow through the core components of
+SvgConform.
+
+. An SVG file is read and parsed into a Document object.
+. The Document is validated against a Profile using the Validator.
+. The Validator applies Requirements and collects results in a ConformanceReport object.
+. If fixing is enabled, the Validator uses the RemediationEngine to apply Remediations.
+. The fixed Document is returned along with the validation results in the ConformanceReport.
+
+[source]
+----
+┌─────────────┐    ┌─────────────┐    ┌─────────────┐
+│  SVG File   │───▶│  Document   │───▶│  Validator  │
+│             │    │   Parser    │    │             │
+└─────────────┘    └─────────────┘    └─────┬───────┘
+                                            │
+                   ┌─────────────┐          │
+                   │   Profile   │◀─────────┘
+                   └─────┬───────┘
+                         │
+                   ┌─────▼───────┐
+                   │    Rules    │
+                   └─────┬───────┘
+                         │
+                   ┌─────▼───────┐    ┌─────────────┐
+                   │Requirements │───▶│ Validation  │
+                   │             │    │   Result    │
+                   └─────────────┘    └─────┬───────┘
+                                            │
+                   ┌─────────────┐          │
+                   │Remediations │◀─────────┘
+                   └─────┬───────┘
+                         │
+                 ┌───────▼────────┐
+                 │ Fixed Document │
+                 └────────────────┘
+----
+
+=== Classes
+
+==== Document (`SvgConform::Document`)
+
+Represents an SVG document. The SVG document in XML is parsed using the `Moxml`
+library, and provides SVG-specific functionality through the Document class.
+
+==== Validator (`SvgConform::Validator`)
+
+The validator is the main entry point for SVG validation. It orchestrates the
+validation process with loading profiles, applying rules, and collecting results.
+
+==== Profile (`SvgConform::Profile`)
+
+A profile is a collection of requirements and remediations that define a specific
+SVG conformance standard. Profiles are defined in YAML configuration files and are
+loaded dynamically at runtime.
+
+Notice that there are requirement violations that cannot be automatically
+remediated. For example, if an SVG uses a forbidden element, the remediation may
+simply remove it, which could lead to loss of important content.
+
+
+==== Requirements
+
+An SvgConform requirement is a specific validation check that determines if an SVG
+document meets certain criteria. Requirements are implemented as classes that inherit
+from `SvgConform::Requirements::BaseRequirement`.
+
+Each requirement class focuses on a single concern implemented using
+XML tree traversal and validation logic.
+
+Every requirement check can be configured with specific parameters to fine-tune
+its behavior.
+
+Profiles can include multiple requirements to cover various aspects of SVG
+conformance.
+
+==== Remediations
+
+An SvgConform remediation is an automatic fixing action that can be applied to
+an SVG document to resolve one or more requirement failures. Remediations are
+implemented as classes that inherit from `SvgConform::Remediations::BaseRemediation`.
+
+Each remediation class focuses on a specific fixing action implemented using
+XML tree manipulation and editing.
+
+Every remediation can be configured with specific parameters to customize its
+behavior. A remediation can target one or more specific requirements through
+configuration options.
+
+
+
+[[command_line_interface]]
+== Command line interface
+
+=== General
+
+The `svg_conform` command provides a comprehensive CLI for validation and fixing.
+
+
+=== `svg_conform profiles`
+
+The `profiles` command lists all available SVG profiles included in SvgConform.
+
+Syntax:
+
+[source,bash]
+----
+svg_conform profiles [OPTIONS]
+
+Options:
+  -v, --verbose           Show detailed profile information
+----
+
+[example]
+====
+[source,bash]
+----
+# List all profiles
+$ svg_conform profiles
+
+Available SVG Profiles
+========================================
+
+╭──────────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ Profile              │ Description                                                                                                       │
+├──────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
+│ base                 │ Base SVG validation profile with common requirements                                                              │
+│ lucid_fix            │ Lucid SVG Fix Profile - Removes invalid use element references and namespace attributes from Lucid-generated SVGs │
+│ metanorma            │ Metanorma SVG Profile - SVG requirements for Metanorma technical documents with embedded resources                │
+│ no_external_css      │ Security-focused profile that disallows external CSS references                                                   │
+│ svg_1_2_rfc          │ SVG 1.2 RFC Profile (RFC 7996) - Black and white diagrams for technical documents                                 │
+│ svg_1_2_rfc_with_rdf │ SVG 1.2 RFC Profile with RDF metadata support - Allows RDF/Dublin Core metadata in SVG files                      │
+╰──────────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+----
+====
+
+
+
+=== `svg_conform check`
+
+The `check` command validates SVG files against a specified profile and optionally
+applies automatic remediations. It supports single files, multiple files via shell
+glob expansion, and directory scanning.
+
+Syntax:
+
+[source,bash]
+----
+svg_conform check [*FILES] [OPTIONS]
+svg_conform check --directory PATH [OPTIONS]
+
+Required Options:
+  -p, --profile PROFILE         Profile to validate against
+
+Input Options:
+  -d, --directory PATH          Directory to scan recursively for SVG files
+
+Remediation Options:
+  -f, --fix                     Enable automatic remediation
+      --output-dir DIR          Output directory for remediated files (required for multi-file)
+      --in-place                Replace original files (requires --force)
+      --force                   Confirm destructive operations
+      --fix-output FILE         Output file for single file mode (default: FILE.fixed.svg)
+
+Reporting Options:
+      --format FORMAT           Output format for single file: table, yaml, json (default: table)
+  -o, --output FILE             Output file for single file mode
+      --report-format FORMAT    Batch report format: json, yaml
+      --report-output FILE      Save detailed batch report to file
+      --manifest FILE           Manifest file path (default: manifest.json with --fix)
+  -q, --quiet                   Suppress per-file output, show summary only
+  -v, --verbose                 Show detailed progress
+----
+
+The check command supports three operational modes:
+
+**Single File Mode:**
+
+Validates a single SVG file and outputs a detailed validation report.
+
+[source,bash]
+----
+# Basic validation
+svg_conform check file.svg -p metanorma
+
+# With remediation
+svg_conform check file.svg -p metanorma -f --fix-output fixed.svg
+
+# Output YAML report
+svg_conform check file.svg -p metanorma --format yaml -o report.yaml
+----
+
+**Multiple Files Mode (Shell Glob):**
+
+Validates multiple files specified via shell glob patterns. The shell expands
+patterns like `*.svg` before passing to the command.
+
+[source,bash]
+----
+# Validate all SVG files in current directory
+svg_conform check *.svg -p metanorma
+
+# Validate with pattern matching
+svg_conform check images/*/*.svg -p metanorma
+
+# Fix multiple files
+svg_conform check *.svg -p metanorma -f --output-dir fixed/
+
+# With JSON batch report
+svg_conform check *.svg -p metanorma --report-format json --report-output report.json
+----
+
+**Directory Mode:**
+
+Recursively scans a directory for all SVG files using the `--directory` or `-d` flag.
+
+[source,bash]
+----
+# Scan directory and validate
+svg_conform check -d images/ -p metanorma
+
+# Scan and remediate to new directory
+svg_conform check -d images/ -p metanorma -f --output-dir fixed/
+
+# Replace files in place (requires confirmation)
+svg_conform check -d images/ -p metanorma -f --in-place --force
+
+# Quiet mode with detailed JSON report
+svg_conform check -d images/ -p metanorma -f --output-dir fixed/ --quiet \
+  --report-format json --report-output report.json
+
+# With custom manifest file
+svg_conform check -d images/ -p metanorma -f --output-dir fixed/ --manifest mappings.json
+----
+
+**Batch Report Format:**
+
+When processing multiple files or directories, a batch summary is displayed:
+
+[source]
+----
+BATCH VALIDATION SUMMARY
+Directory: /path/to/images
+Profile: metanorma
+Files processed: 56
+Valid before: 0
+Remediated: 56
+Valid after: 56
+Failed: 0
+Success rate: 100.0%
+Manifest written to manifest.json
+----
+
+If `--report-format` is specified, a detailed report is generated in JSON or
+YAML format using lutaml-model serialization:
+
+[source,json]
+----
+{
+  "directory": "/path/to/images",
+  "profile": "metanorma",
+  "timestamp": "2025-10-12T15:36:25+08:00",
+  "total_files": 56,
+  "valid_before": 0,
+  "valid_after": 56,
+  "remediated": 56,
+  "failed": 0,
+  "success_rate": 100.0,
+  "files": [
+    {
+      "filename": "diagram.svg",
+      "original_path": "/path/to/images/diagram.svg",
+      "valid_before": false,
+      "valid_after": true,
+      "errors_before": 3,
+      "errors_after": 0,
+      "remediated_path": "/path/to/fixed/diagram.svg",
+      "status": "remediated"
+    }
+  ],
+  "manifest": {
+    "/path/to/images/diagram.svg": "/path/to/fixed/diagram.svg"
+  }
+}
+----
+
+**Manifest File:**
+
+When using `--fix`, a manifest file is automatically created (or can be
+explicitly specified with `--manifest`). The manifest maps original file paths
+to their remediated counterparts:
+
+[source,json]
+----
+{
+  "timestamp": "2025-10-12T15:00:00+08:00",
+  "profile": "metanorma",
+  "mappings": {
+    "/original/path/file1.svg": "/fixed/path/file1.svg",
+    "/original/path/file2.svg": "/fixed/path/file2.svg"
+  }
+}
+----
+
+
+=== `svg_conform version`
+
+The `version` command displays the current version of SvgConform.
+
+Syntax:
+
+[source,bash]
+----
+svg_conform version
+----
+
+[example]
+[source,bash]
+----
+$ svg_conform version
+SvgConform 0.1.0
+----
+
+
+
+[[ruby_api_reference]]
+== Ruby API
+
+=== Basic usage
+
+[source,ruby]
+----
+require 'svg_conform'
+
+# Validate a file
+result = SvgConform.validate_file('diagram.svg', profile: :svg_1_2_rfc)
+
+# Check validation status
+puts "Valid: #{result.valid?}"
+puts "Errors: #{result.errors.count}"
+puts "Warnings: #{result.warnings.count}"
+
+# Get detailed error information
+result.errors.each do |error|
+  puts "#{error.rule.id}: #{error.message}"
+  puts "  Element: #{error.element}" if error.element
+  puts "  Location: #{error.location}" if error.location
+end
+----
+
+=== Advanced usage
+
+[source,ruby]
+----
+# Create validator instance
+validator = SvgConform::Validator.new
+
+# Validate with custom options
+result = validator.validate_file('diagram.svg',
+  profile: :svg_1_2_rfc,
+  fix: true,
+  strict: false
+)
+
+# Access fixed document
+if result.fixed?
+  fixed_svg = result.fixed_document.to_xml
+  File.write('diagram_fixed.svg', fixed_svg)
+end
+
+# Get profile information
+profile_info = validator.profile_info(:svg_1_2_rfc)
+puts "Profile: #{profile_info[:name]}"
+puts "Description: #{profile_info[:description]}"
+puts "Rules: #{profile_info[:rules].map { |r| r[:id] }.join(', ')}"
+----
+
+=== Working with loaded SVG content
+
+[source,ruby]
+----
+# Parse SVG content
+document = SvgConform::Document.from_content(svg_string)
+
+# Access document elements
+root = document.root
+puts "Root element: #{root.name}"
+puts "Namespace: #{root.namespace}"
+
+# Find elements
+circles = document.find_elements('circle')
+texts = document.find_elements('text')
+
+# Modify document
+fixer = SvgConform::Fixer.new(document)
+fixer.remove_element(some_element)
+fixer.set_attribute(element, 'fill', 'black')
+
+# Get modified XML
+modified_svg = fixer.to_xml
+----
+
+
+== Configuration
+
+=== Profile configuration
+
+Profiles can be configured using YAML files in the `config/profiles/` directory:
+
+[source,yaml]
+----
+# config/profiles/custom.yml
+name: "Custom Profile"
+description: "Custom SVG profile for specific requirements"
+extends: "base"  # Optional: inherit from another profile
+
+rules:
+  - id: "namespace"
+    type: "namespace_rule"
+    config:
+      required_namespace: "http://www.w3.org/2000/svg"
+
+  - id: "allowed_elements"
+    type: "allowed_elements_rule"
+    config:
+      allowed_elements:
+        - "svg"
+        - "g"
+        - "rect"
+        - "circle"
+        - "path"
+        - "text"
+
+  - id: "color_restrictions"
+    type: "color_restrictions_rule"
+    config:
+      grayscale_only: true
+      allowed_colors:
+        - "black"
+        - "white"
+        - "gray"
+----
+
+=== Requirement configuration
+
+TODO.
+
+=== Remediation configuration
+
+TODO.
+
+
+== Extending SvgConform
+
+=== Custom profiles
+
+Create a new profile by defining a YAML configuration:
+
+[source,yaml]
+----
+# config/profiles/my_organization.yml
+profile:
+  name: "My Organization SVG Profile"
+  description: "SVG profile for internal use"
+  import: "base"  # Optional: inherit from another profile
+
+requirements:
+  - id: "namespace"
+    type: "NamespaceRequirement"
+    description: "Ensure proper SVG namespace"
+
+  - id: "custom_requirement"
+    type: "CustomRequirement"
+    description: "Validate custom elements"
+    config:
+      custom_option: "organization_value"
+
+  - id: "security_restrictions"
+    type: "NoExternalCssRequirement"
+    description: "Prevent external CSS references"
+
+remediations:
+  - id: "fix_namespace"
+    type: "NamespaceRemediationAction"
+    description: "Add missing SVG namespace"
+    targets: ["namespace"]
+
+  - id: "fix_custom_elements"
+    type: "CustomRemediationAction"
+    description: "Fix custom element issues"
+    targets: ["custom_requirement"]
+    config:
+      default_value: "organization_default"
+----
+
+Then load the profile:
+
+[source,ruby]
+----
+# Load and use the custom profile
+profile = SvgConform::Profile.load_from_file('config/profiles/my_organization.yml')
+document = SvgConform::Document.new(svg_content)
+result = profile.validate(document)
+
+# Apply remediations if needed
+if !result.valid? && profile.has_remediations?
+  engine = SvgConform::RemediationEngine.new(profile)
+  remediation_results = engine.apply_remediations(document, result)
+end
+----
+
+[[external_compliance]]
+== External compliance
+
+=== General
+
+SvgConform supports external compliance validation through compatibility testing
+and comparison with external SVG validation tools.
+
+SvgConform provides validation report comparison capabilities that enable
+assessment of compatibility with external SVG validation tools. This supports
+migration workflows and quality assurance processes.
+
+=== svgcheck
+
+IETF provides the `svgcheck` tool, a Python-based SVG validator and fixer
+that checks SVG files against the SVG 1.2 RFC profile defined in RFC 7996.
+
+SvgConform supports validation compatibility testing against the IETF Python
+svgcheck tool for SVG 1.2 RFC validation.
+
+SvgConform includes a compatibility analysis feature that compares its
+validation results with those of `svgcheck`, helping users identify any
+discrepancies or issues.
+
+IMPORTANT: As of version 2025-10-12, SvgConform's SVG 1.2 RFC profile provides a
+100% match in check and repair modes of svgcheck for all test files, except for
+the `full-tiny.svg` file, which svgcheck marks as invalid and fails to repair.
+
+
+=== svgcheck testing workflow
+
+The external compliance testing workflow involves generating reference outputs
+from external tools and comparing validation results:
+
+[source,bash]
+----
+# 1. Generate external tool outputs for reference
+svg_conform svgcheck generate SVGCHECK_REPO_LOCAL_PATH --mode both
+
+# 2. Generate comparison reports
+svg_conform svgcheck compatibility --output comparison_report.json
+----
+
+
+=== svgcheck compatibility architecture
+
+SvgConform provides compatibility with the IETF Python svgcheck tool through a
+sophisticated mapping and comparison system that enables validation against the
+SVG 1.2 RFC profile.
+
+.Architecture of svgcheck compatibility checks
+[source]
+----
+╭────────────────────────────────────────────────────────────────╮
+│                svgcheck Compatibility System                   │
+│           (SvgConform ↔ svgcheck Python tool)                  │
+├────────────────────────────────────────────────────────────────┤
+│                                                                │
+│  ╭─────────────╮    ╭─────────────────────────────────────╮    │
+│  │ svgcheck    │    │        YAML Mapping                 │    │
+│  │ Raw Errors  │───▶│    config/svgcheck_mapping.yml      │    │
+│  │ (Python)    │    │                                     │    │
+│  ╰─────────────╯    │ • Pattern matching with regex       │    │
+│                     │ • Requirement categorization        │    │
+│                     │ • Semantic meaning extraction       │    │
+│                     │ • Unmapped error detection          │    │
+│                     ╰─────────────┬───────────────────────╯    │
+│                                   │                            │
+│  ╭────────────────────────────────▼────────────────────────╮   │
+│  │              SvgcheckParser                             │   │
+│  │                                                         │   │
+│  │ • Applies YAML mapping during parsing                   │   │
+│  │ • Categorizes errors by requirement                     │   │
+│  │ • Marks unmapped errors for RED display                 │   │
+│  │ • Creates properly structured ConformanceReport         │   │
+│  ╰─────────────────────────┬───────────────────────────────╯   │
+│                            │                                   │
+│                            ▼                                   │
+│  ╭─────────────────────────────────────────────────────────╮   │
+│  │              Parallel Processing                        │   │
+│  │                                                         │   │
+│  │ ╭─────────────────────╮   ╭─────────────────────────╮   │   │
+│  │ │   SvgConform        │   │     svgcheck            │   │   │
+│  │ │   Validation        │   │   ConformanceReport     │   │   │
+│  │ │                     │   │   (mapped)              │   │   │
+│  │ │ • Native Ruby       │   │ • Parsed from YAML      │   │   │
+│  │ │ • Direct profile    │   │ • Requirement-mapped    │   │   │
+│  │ │ • ConformanceReport │   │ • Compatible structure  │   │   │
+│  │ ╰─────────────────────╯   ╰─────────────────────────╯   │   │
+│  ╰─────────────┬───────────────────────┬───────────────────╯   │
+│                │                       │                       │
+│                └───────────┬───────────┘                       │
+│                            │                                   │
+│  ╭─────────────────────────▼─────────────────────────╮         │
+│  │              ReportComparator                     │         │
+│  │                                                   │         │
+│  │ • Direct ConformanceReport comparison             │         │
+│  │ • Unified requirement-based display               │         │
+│  │ • Side-by-side error mapping                      │         │
+│  │ • 🚨 RED highlighting for unmapped errors         │         │
+│  │ • Compatibility metrics and analysis              │         │
+│  ╰───────────────────────────────────────────────────╯         │
+│                                                                │
+╰────────────────────────────────────────────────────────────────╯
+----
+
+
+=== svgcheck compatibility commands
+
+==== General
+
+In order to run the compatibility commands, you need to have the `svgcheck` tool
+installed and accessible in your PATH.
+
+NOTE: The `svgcheck` tool can be installed via `pip install svgcheck`.
+
+The commands in this section provide functionality to generate svgcheck outputs
+for test files and perform compatibility analysis between SvgConform and svgcheck
+results.
+
+The test files from svgcheck are included in the SvgConform repository under
+`spec/fixtures/svgcheck` to ensure consistent testing.
+
+The mapping configuration file `config/svgcheck_mapping.yml` defines how
+svgcheck error messages are interpreted and mapped to SvgConform requirements.
+
+The data flow steps for compatibility analysis is as follows:
+
+. svgcheck outputs are generated for test files using the `svgcheck generate` command.
+
+. For each test file, svgcheck outputs are generated in both check-only and
+repair modes through the `svgcheck generate` command, and are then parsed by the
+`Svgcheck::Parser` class into the `ReportGenerator` class.
+
+. SvgConform validates the same test files using the SVG 1.2 RFC profile, which provides
+a `ConformanceReport` object.
+
+. The `ReportComparator` class compares the `ConformanceReport` from SvgConform
+with the svgcheck `ReportGenerator` results. The `ReportComparator` handles
+both check-only and repair mode outputs, and maps svgcheck messages to SvgConform
+requirements and remediations outcomes.
+
+. A detailed comparison report is generated, highlighting matches and discrepancies.
+
+
+
+==== `svg_conform svgcheck compatibility`
+
+The `svgcheck compatibility` command performs a comprehensive compatibility analysis
+between SvgConform validation results and the IETF `svgcheck` tool output.
+
+[source,bash]
+----
+svg_conform svgcheck compatibility [OPTIONS] [FILE]
+
+Options:
+  -p, --profile PROFILE    Profile to use (default: svg_1_2_rfc)
+  -f, --file FILE          Analyze specific file instead of all test files
+  -o, --output FILE        Output clean report to file (no color codes)
+  -v, --verbose            Verbose output
+----
+
+[example]
+====
+[source,bash]
+----
+# Run comprehensive compatibility analysis
+svg_conform svgcheck compatibility
+
+# Analyze specific file
+svg_conform svgcheck compatibility --file example.svg
+
+# Generate clean report for documentation
+svg_conform svgcheck compatibility --output compatibility-report.md
+
+# Analyze specific file and save to file
+svg_conform svgcheck compatibility --file example.svg --output analysis.md
+----
+====
+
+
+==== `svg_conform svgcheck generate`
+
+The `svgcheck generate` command generates svgcheck outputs for test files to
+facilitate compatibility analysis.
+
+These files are generated in a structured output directory, with separate subdirectories
+for check-only and repair modes.
+
+
+[source,bash]
+----
+Usage:
+  svg_conform svgcheck generate SVGCHECK_REPO_PATH
+
+Options:
+  -m, [--mode=MODE]                                  # Generation mode: check, repair, or both
+                                                     # Default: both
+                                                     # Possible values: check, repair, both
+      [--svgcheck-exec=SVGCHECK_EXEC]                # Path to svgcheck executable
+      [--fixtures-path=FIXTURES_PATH]                # Output directory (default: spec/fixtures/svgcheck)
+  -f, [--single-file=SINGLE_FILE]                    # Process single file only
+      [--force]                                      # Overwrite existing outputs
+                                                     # Default: false
+  -v, [--verbose], [--no-verbose], [--skip-verbose]  # Verbose output
+                                                     # Default: false
+
+Description:
+  Generate svgcheck outputs for test files by running svgcheck on them.
+
+  SVGCHECK_REPO_PATH: Path to the svgcheck repository (e.g., svgcheck-reference)
+
+  By default, processes all test files in SVGCHECK_REPO_PATH/svgcheck/Tests/ and generates BOTH check and repair
+  outputs in separate subdirectories.
+
+  Examples: svg_conform svgcheck generate svgcheck-reference svg_conform svgcheck generate svgcheck-reference --mode
+  check svg_conform svgcheck generate svgcheck-reference --single-file example.svg
+----
+
+This command provides a bridge between SvgConform and the Python svgcheck tool,
+enabling comprehensive compatibility testing and analysis. By default, it
+generates both check and repair outputs in separate subdirectories.
+
+The command creates a structured output directory with separate subdirectories
+for different svgcheck modes:
+
+[source]
+----
+spec/fixtures/svgcheck/
+├── check/          # Check-only outputs (validation without remediation)
+│   ├── file1.svg.out   # Validation messages from svgcheck
+│   ├── file1.svg.err   # Error messages from svgcheck
+│   └── file1.svg.code  # Exit status from svgcheck
+└── repair/         # Repair outputs (validation + remediation)
+    ├── file1.svg.out   # Validation messages from svgcheck
+    ├── file1.svg.err   # Error messages from svgcheck
+    ├── file1.svg.code  # Exit status from svgcheck
+    └── file1.svg.file  # Remediated SVG content
+----
+
+Some svgcheck test files are renamed to indicate their actual type of content,
+which is defined in `svgcheck_generate.rb`:
+
+* svgcheck `full-tiny.xml` is renamed to `full-tiny.svg`
+* svgcheck `rfc-svg.xml` is renamed to `rfc-svg.svg`
+
+The generated outputs are used by the `compatibility` command to perform
+detailed comparisons between SvgConform and svgcheck validation results. The
+structured directory layout enables:
+
+- **Targeted analysis**: Compare check-only vs repair mode behaviors
+- **Comprehensive testing**: Validate against both validation and remediation workflows
+- **Regression testing**: Track changes in svgcheck behavior over time
+- **Profile development**: Use svgcheck outputs as reference for profile refinement
+
+
+There are three modes of operation for generating svgcheck outputs:
+
+**Check Mode** (`--mode check`):
+
+- Runs svgcheck without the `--repair` flag
+- Only validates SVG files and reports errors
+- Generates `.out`, `.err`, and `.code` files
+- No remediated content is produced
+
+**Repair Mode** (`--mode repair`):
+
+- Runs svgcheck with the `--repair` flag
+- Validates SVG files and generates remediated content
+- Generates `.out`, `.err`, `.code`, and `.file` files
+- The `.file` contains the remediated SVG content
+
+**Both Mode** (`--mode both`, default):
+
+- Runs both check and repair modes for each file
+- Generates complete output sets in both subdirectories
+- Provides comprehensive data for compatibility analysis
+
+[source,bash]
+----
+# Generate both check and repair outputs for all test files
+svg_conform svgcheck generate /path/to/svgcheck-reference
+
+# Generate only check outputs
+svg_conform svgcheck generate /path/to/svgcheck-reference --mode check
+
+# Generate only repair outputs
+svg_conform svgcheck generate /path/to/svgcheck-reference --mode repair
+
+# Process a single file with verbose output
+svg_conform svgcheck generate /path/to/svgcheck-reference --single-file example.svg --verbose
+
+# Force regeneration of existing outputs
+svg_conform svgcheck generate /path/to/svgcheck-reference --force
+
+# Use custom output directory
+svg_conform svgcheck generate /path/to/svgcheck-reference --fixtures-path /path/to/custom/output
+----
+
+
+
+==== `svg_conform svgcheck compare`
+
+The `svgcheck compare` command compares SvgConform validation results with existing
+svgcheck reports to assess compatibility.
+
+This command is useful for verifying that SvgConform produces equivalent results
+to the IETF svgcheck tool.
+
+Syntax:
+
+[source,bash]
+----
+svg_conform svgcheck compare FILE [OPTIONS]
+
+Options:
+  -p, --profile PROFILE        Profile to use (default: svg_1_2_rfc)
+      --svgcheck-report FILE   Path to svgcheck report (default: auto-detect)
+----
+
+[example]
+====
+[source,bash]
+----
+# Compare with auto-detected svgcheck report
+$ svg_conform svgcheck compare diagram.svg -p svg_1_2_rfc
+
+# Specify svgcheck report explicitly
+$ svg_conform svgcheck compare diagram.svg --svgcheck-report diagram.svg.svgcheck.yaml
+----
+====
+
+
+== Testing
+
+Run the test suite:
+
+[source,bash]
+----
+bundle exec rspec
+----
+
+Run specific test categories:
+
+[source,bash]
+----
+# Unit tests
+bundle exec rspec spec/unit/
+
+# Integration tests
+bundle exec rspec spec/integration/
+
+# SVGCheck compatibility tests
+bundle exec rspec spec/svgcheck_compatibility_spec.rb
+----
+
+
+== Changelog
+
+See link:CHANGELOG.md[CHANGELOG.md] for version history and changes.
+
+
+== Copyright and license
+
+Copyright Ribose.
+
+This gem is available as open source under the terms of the Ribose 2-clause BSD
+license.