serialbench 0.1.0 → 0.1.2

data/README.adoc

@@ -1,592 +1,558 @@
-= Serialbench: Comprehensive serialization benchmarking suite for Ruby
+= Serialbench: Ruby serialization library performance benchmarker
 
 image:https://img.shields.io/gem/v/serialbench.svg["Gem Version", link="https://rubygems.org/gems/serialbench"]
-image:https://github.com/example/serialbench/actions/workflows/rake.yml/badge.svg["Build Status", link="https://github.com/example/serialbench/actions/workflows/rake.yml"]
-image:https://img.shields.io/github/issues-pr-raw/example/serialbench.svg["Pull Requests", link="https://github.com/example/serialbench/pulls"]
-image:https://img.shields.io/github/commits-since/example/serialbench/latest.svg["Commits since latest",link="https://github.com/example/serialbench/releases"]
+image:https://github.com/metanorma/serialbench/actions/workflows/ci.yml/badge.svg["Build Status", link="https://github.com/metanorma/serialbench/actions/workflows/ci.yml"]
+image:https://github.com/metanorma/serialbench/actions/workflows/benchmark.yml/badge.svg["Benchmark Status", link="https://github.com/metanorma/serialbench/actions/workflows/benchmark.yml"]
+image:https://img.shields.io/github/issues-pr-raw/metanorma/serialbench.svg["Pull Requests", link="https://github.com/metanorma/serialbench/pulls"]
 
-== Purpose
+== Overview
 
-Serialbench is a comprehensive benchmarking suite that evaluates the performance of popular Ruby serialization libraries across multiple formats and dimensions including parsing speed, generation speed, memory usage, and feature completeness.
+Serialbench is a comprehensive benchmarking suite that evaluates the performance of popular Ruby serialization libraries across multiple formats. It provides detailed performance comparisons and analysis to help developers make informed decisions when choosing serialization libraries for their Ruby applications.
 
-This tool helps developers make informed decisions when choosing serialization libraries for their Ruby applications by providing detailed performance comparisons and analysis across XML, JSON, and TOML formats.
+**Supported Formats**: XML, JSON, YAML, TOML, and more
 
-=== Tested XML libraries
+**Key Metrics**: Parsing speed, generation speed, memory usage, streaming capabilities, and feature completeness
 
-==== Core XML Libraries
-* **Ox** - High-performance XML parser optimized for speed and low memory usage
-* **Nokogiri** - Feature-rich XML/HTML parser with XPath support and comprehensive DOM manipulation
-* **LibXML** - Ruby bindings for the libxml2 C library with excellent performance characteristics
-* **Oga** - Pure Ruby XML parser with XPath support and streaming capabilities
-* **REXML** - Ruby's built-in XML parser with streaming support (reference implementation)
+**Multi-Environment Support**: Docker and ASDF-based multi-Ruby version benchmarking with automated result aggregation and HTML site generation
 
-==== Additional Format Support
-* **JSON** - Ruby's built-in JSON parser (for comparison baseline)
-* **Oj** - High-performance JSON parser with streaming support (for comparison baseline)
-* **YAJL** - Yet Another JSON Library with streaming support (for comparison baseline)
-* **TOML-RB** - Ruby TOML parser (for comparison baseline)
-* **Tomlib** - Fast TOML parser (for comparison baseline)
+== Supported serialization libraries
 
-== Installation
+[cols="1,3,1,4", options="header"]
+|===
+| Format | Name | Version | Description
+
+| XML
+| https://github.com/ohler55/ox[Ox]
+| v2.14.23
+| C extension XML parser
+
+| XML
+| https://github.com/xml4r/libxml-ruby[LibXML]
+| v4.1.2
+| Ruby bindings for libxml2
+
+| XML
+| https://github.com/sparklemotion/nokogiri[Nokogiri]
+| v1.18.8
+| XML/HTML parser with XPath and CSS selectors
+
+| XML
+| https://github.com/YorickPeterse/oga[Oga]
+| v3.4
+| Pure Ruby XML parser with XPath support
+
+| XML
+| https://github.com/ruby/rexml[REXML]
+| v3.4.1
+| Ruby's standard library XML parser
+
+| JSON
+| https://github.com/ohler55/oj[Oj]
+| v3.16.11
+| JSON parser with multiple parsing modes
+
+| JSON
+| https://github.com/brianmario/yajl-ruby[YAJL]
+| v1.4.3
+| JSON library with streaming capabilities
+
+| JSON
+| https://github.com/flori/json[JSON]
+| v2.12.2
+| Ruby's standard library JSON parser
+
+| YAML
+| https://github.com/ruby/psych[Psych]
+| v5.1.2
+| Ruby's standard library YAML parser
+
+| YAML
+| https://github.com/ruby/syck[Syck]
+| v1.5.1.1
+| Legacy YAML parser
+
+| TOML
+| https://github.com/fbernier/tomlib[Tomlib]
+| v0.7.3
+| TOML parser implemented in C
+
+| TOML
+| https://github.com/emancu/toml-rb[TOML-RB]
+| v2.2.0
+| Pure Ruby TOML parser
+
+| TOML
+| https://github.com/fbernier/tomlrb[tomlrb]
+| v2.0.3
+| A Racc based TOML Ruby parser (Only supports parsing, no support for dumping/writing.)
 
-Add this line to your application's Gemfile:
+|===
 
-[source,ruby]
-----
-gem 'serialbench'
-----
 
-And then execute:
+== Data formats and schema
 
-[source,shell]
-----
-$ bundle install
-----
+Serialbench generates structured YAML output for benchmark results, with
+different formats for single-environment and multi-environment runs.
 
-Or install it yourself as:
+The data formats include:
 
-[source,shell]
-----
-$ gem install serialbench
-----
+* **Single benchmark results**: Individual benchmark run output
+* **Result set data structure**: Multi-platform benchmark aggregation
+* **JSON schema specification**: Complete schema validation rules
+* **Configuration file formats**: Docker and ASDF configuration examples
 
-=== XML library dependencies
+== Prerequisites
 
-To run benchmarks for all supported XML libraries, install the following gems:
+=== System requirements
 
-[source,shell]
-----
-# Core XML libraries
-$ gem install ox nokogiri libxml-ruby oga
+* **Ruby**: 3.0 or later (3.3+ recommended for best performance)
+* **Operating system**: Linux, macOS, or Windows
+* **Architecture**: x86_64 or ARM64
 
-# Additional format libraries (for comparison)
-$ gem install oj toml-rb
+=== Library dependencies
 
-# Memory profiling support
-$ gem install memory_profiler
-----
-
-NOTE: REXML and JSON are included with Ruby and require no additional installation.
-
-=== Library-specific installation notes
-
-==== Ox
-High-performance C extension requiring compilation:
-[source,shell]
-----
-$ gem install ox
-----
+**System dependencies** (required for some native extensions):
 
-==== Nokogiri
-May require system dependencies on some platforms:
-[source,shell]
+[source,bash]
 ----
 # macOS with Homebrew
 $ brew install libxml2 libxslt
-$ gem install nokogiri
-
-# Ubuntu/Debian
-$ sudo apt-get install libxml2-dev libxslt1-dev
-$ gem install nokogiri
-----
-
-==== LibXML
-Ruby bindings for libxml2:
-[source,shell]
-----
-# macOS with Homebrew
-$ brew install libxml2
-$ gem install libxml-ruby
 
 # Ubuntu/Debian
-$ sudo apt-get install libxml2-dev
-$ gem install libxml-ruby
-----
+$ sudo apt-get install libxml2-dev libxslt1-dev build-essential
 
-==== Oga
-Pure Ruby implementation with no system dependencies:
-[source,shell]
-----
-$ gem install oga
+# CentOS/RHEL/Fedora
+$ sudo yum install libxml2-devel libxslt-devel gcc gcc-c++
 ----
 
-== Usage
-
-=== Command line interface
+== Installation
 
-Run the complete XML benchmark suite:
+Add this line to your application's Gemfile:
 
-[source,shell]
+[source,ruby]
 ----
-$ serialbench benchmark
+gem 'serialbench'
 ----
 
-Run XML-only benchmarks:
+And then execute:
 
-[source,shell]
+[source]
 ----
-$ serialbench benchmark --formats xml
+$ bundle install
 ----
 
-Run benchmarks with comparison formats:
+Or install it yourself as:
 
-[source,shell]
+[source]
 ----
-$ serialbench benchmark --formats xml json
-$ serialbench benchmark --formats xml json toml
+$ gem install serialbench
 ----
 
-Run only DOM parsing benchmarks:
-
-[source,shell]
-----
-$ serialbench benchmark --parsing-only
-----
 
-Run only XML generation benchmarks:
+== Command line interface
 
-[source,shell]
-----
-$ serialbench benchmark --generation-only
-----
+Serialbench provides a comprehensive Thor-based CLI with four main subcommands
+for managing environments, benchmarks, result sets, and Ruby builds.
 
-Run only streaming/SAX parsing benchmarks:
+=== Main Commands Overview
 
-[source,shell]
+[source,sh]
 ----
-$ serialbench benchmark --streaming-only
-----
-
-Output results in JSON format only:
+$ serialbench
+Serialbench - Benchmarking Framework for Ruby Serialization Libraries
 
-[source,shell]
-----
-$ serialbench benchmark --output-format json
-----
+USAGE:
+  serialbench COMMAND [SUBCOMMAND] [OPTIONS]
 
-List available XML parsers:
+COMMANDS:
+  environment   Manage benchmark environments (Docker, ASDF, Local)
+  benchmark     Manage individual benchmark runs
+  resultset     Manage benchmark resultsets (collections of runs)
+  ruby-build    Manage Ruby-Build definitions for validation
+  version       Show version information
+  help          Show this help message
 
-[source,shell]
-----
-$ serialbench list
-$ serialbench list --format xml
-----
+EXAMPLES:
+  # Create a Docker environment
+  serialbench environment new docker-test docker
 
-Show help information:
+  # Run multi-environment benchmarks
+  serialbench environment multi-execute asdf --config=serialbench-asdf.yml
+  serialbench environment multi-execute docker --config=serialbench-docker.yml
 
-[source,shell]
-----
-$ serialbench help
-$ serialbench help benchmark
-----
+  # Create and execute a benchmark
+  serialbench benchmark create my-benchmark
+  serialbench benchmark execute my-benchmark.yml
 
-Show version:
+  # Create a result set for comparison
+  serialbench resultset create comparison-set
+  serialbench resultset add-result comparison-set results/my-benchmark
 
-[source,shell]
-----
-$ serialbench version
+  # Generate static sites
+  serialbench benchmark build-site results/my-benchmark
+  serialbench resultset build-site resultsets/comparison-set
 ----
 
-=== XML-specific benchmark options
+=== Environment management
 
-Run benchmarks for specific XML libraries only:
+The `environment` subcommand manages environment configurations and executes
+benchmarks across different Ruby environments.
 
-[source,shell]
+[source]
 ----
-$ serialbench benchmark --formats xml --parsers ox,nokogiri
-$ serialbench benchmark --formats xml --parsers rexml,oga
+$ serialbench environment help
+Commands:
+  serialbench environment execute ENVIRONMENT_CONFIG BENCHMARK_CONFIG RESULT_PATH  # Execute benchmark in environment
+  serialbench environment help [COMMAND]                                           # Describe subcommands or one specific subcommand
+  serialbench environment new NAME KIND RUBY_BUILD_TAG                             # Create a new environment configuration
+  serialbench environment prepare ENVIRONMENT_CONFIG                               # Prepare environment for benchmarking
 ----
 
-Run memory-intensive benchmarks:
 
-[source,shell]
-----
-$ serialbench benchmark --formats xml --memory-profiling
-----
+=== Benchmark management
 
-Generate detailed XML processing reports:
+The `benchmark` subcommand handles individual benchmark runs and site generation.
 
-[source,shell]
+[source]
 ----
-$ serialbench benchmark --formats xml --detailed-reports
+$ serialbench benchmark help
+Commands:
+  serialbench benchmark _docker_execute ENVIRONMENT_CONFIG_PATH BENCHMARK_CONFIG_PATH  # (Private) Execute a benchmark run
+  serialbench benchmark build-site RUN_PATH [OUTPUT_DIR]                               # Generate HTML site for a run
+  serialbench benchmark create [NAME]                                                  # Generate a run configuration file
+  serialbench benchmark execute ENVIRONMENT_CONFIG_PATH BENCHMARK_CONFIG_PATH          # Execute a benchmark run
+  serialbench benchmark help [COMMAND]                                                 # Describe subcommands or one specific subcommand
+  serialbench benchmark list                                                           # List all available runs
 ----
 
-=== Multi-Ruby Version Comparison
+The `_docker_execute` command is a private command used internally by the
+`execute` command to run benchmarks in Docker environments.
 
-Merge benchmark results from multiple Ruby versions:
 
-[source,shell]
-----
-$ serialbench merge_results ruby-3.0/results ruby-3.1/results ruby-3.2/results merged_output/
-----
+=== Result set management
 
-Generate GitHub Pages HTML from multiple benchmark runs:
+The `resultset` subcommand manages collections of benchmark runs for comparison analysis.
 
-[source,shell]
+[source]
 ----
-$ serialbench github_pages ruby-3.0/results ruby-3.1/results ruby-3.2/results docs/
+$ serialbench resultset help
+Commands:
+  serialbench resultset add-result RESULT_PATH RESULTSET_PATH     # Add a run to a resultset
+  serialbench resultset build-site RESULTSET_PATH [OUTPUT_DIR]    # Generate HTML site for a resultset
+  serialbench resultset create NAME PATH                          # Create a new resultset
+  serialbench resultset help [COMMAND]                            # Describe subcommands or one specific subcommand
+  serialbench resultset list                                      # List all available resultsets
+  serialbench resultset remove-result RESULTSET_PATH RESULT_PATH  # Remove a run from a resultset
 ----
 
-This creates an interactive HTML report with:
 
-* **Multi-version charts**: Compare performance across Ruby versions
-* **Interactive navigation**: Switch between parsing, generation, streaming, and memory usage
-* **Environment details**: Ruby versions, platforms, and serializer versions
-* **GitHub Pages ready**: Deploy directly to GitHub Pages for public sharing
+=== ruby-build management
 
-=== Programmatic usage
+The `ruby-build` subcommand manages Ruby build definitions and version information.
 
-==== Basic benchmark execution
+Serialbench uses ruby-build definitions of Ruby interpreter types and versions
+for identification.
 
-[source,ruby]
+[source]
+----
+$ serialbench ruby-build help
+Commands:
+  serialbench ruby_build cache-info      # Show information about the Ruby-Build definitions cache
+  serialbench ruby_build help [COMMAND]  # Describe subcommands or one specific subcommand
+  serialbench ruby_build list [FILTER]   # List available Ruby-Build definitions
+  serialbench ruby_build show TAG        # Show details for a specific Ruby-Build definition
+  serialbench ruby_build suggest         # Suggest Ruby-Build tag for current Ruby version
+  serialbench ruby_build update          # Update Ruby-Build definitions from GitHub
+  serialbench ruby_build validate TAG    # Validate a Ruby-Build tag
 ----
-require 'serialbench'
-
-# Run all benchmarks for all formats
-results = Serialbench.run_benchmarks
 
-# Run benchmarks for specific formats
-results = Serialbench.run_benchmarks(formats: [:xml, :json])
 
-# Generate comprehensive reports
-report_files = Serialbench.generate_reports(results)
+== Workflow examples
 
-puts "HTML report: #{report_files[:html]}"
-puts "Charts generated: #{report_files[:charts].length}"
-----
+=== Docker-based testing
 
-==== Custom benchmark configuration
+NOTE: This works.
 
-[source,ruby]
+[source,bash]
 ----
-require 'serialbench'
+# 1. Prepare Docker environment
+$ bundle exec serialbench environment prepare config/environments/docker-ruby-3.1.yml
 
-# Create a custom benchmark runner
-runner = Serialbench::BenchmarkRunner.new(formats: [:json, :xml])
+# 2. Run benchmark
+$ bundle exec serialbench environment execute config/environments/docker-ruby-3.1.yml config/benchmarks/short.yml results/runs/docker-ruby-3.1-results
 
-# Run specific benchmark categories
-parsing_results = runner.run_parsing_benchmarks
-generation_results = runner.run_generation_benchmarks
-memory_results = runner.run_memory_benchmarks
+# 3. Create a resultset
+$ bundle exec serialbench resultset create docker-comparison results/sets/docker-comparison
 
-# Format and display results
-formatter = Serialbench::ResultFormatter.new(runner.results)
-puts formatter.summary
-----
+# 3a. (Optional) Build the site from the result if you want to visualize results
+$ bundle exec serialbench benchmark build-site results/runs/docker-ruby-3.1-results/ --output_dir=_site_result
 
-==== Individual serializer testing
+# 4. Add the result to the resultset
+$ bundle exec serialbench resultset add-result results/sets/docker-comparison/ results/runs/docker-ruby-3.1-results/
 
-[source,ruby]
+# 5. Build the site from the resultset
+$ bundle exec serialbench resultset build-site results/sets/docker-comparison/
+
+# 6. Open the generated site
+$ open _site/index.html
 ----
-require 'serialbench'
 
-# Test a specific JSON serializer
-oj_serializer = Serialbench::Serializers::Json::OjSerializer.new
+=== ASDF-based testing
 
-if oj_serializer.available?
-  json_content = '{"users": [{"name": "Alice", "age": 30}]}'
+WARNING: THIS IS NOT YET WORKING.
 
-  # Parse JSON
-  data = oj_serializer.parse(json_content)
+[source,bash]
+----
+# 1. Validate configuration
+$ bundle exec serialbench benchmark validate serialbench-asdf.yml
 
-  # Generate JSON
-  json_output = oj_serializer.generate(data, pretty: true)
+# 2. Prepare Ruby environments
+$ bundle exec serialbench benchmark prepare asdf --config=serialbench-asdf.yml
 
-  # Stream parsing (if supported)
-  if oj_serializer.supports_streaming?
-    oj_serializer.stream_parse(json_content) do |event, data|
-      puts "Event: #{event}, Data: #{data}"
-    end
-  end
+# 3. Run benchmarks across all Ruby versions
+$ bundle exec serialbench benchmark execute asdf --config=serialbench-asdf.yml
 
-  puts "Serializer: #{oj_serializer.name}"
-  puts "Version: #{oj_serializer.version}"
-  puts "Format: #{oj_serializer.format}"
-  puts "Features: #{oj_serializer.features}"
-end
+# 4. Results are automatically merged and dashboard generated
+$ open asdf-results/_site/index.html
 ----
 
-==== Check available serializers
 
-[source,ruby]
-----
-require 'serialbench'
-
-# List all available serializers
-Serialbench.available_serializers.each do |serializer_class|
-  serializer = serializer_class.new
-  puts "#{serializer.format}: #{serializer.name} v#{serializer.version}"
-end
 
-# List serializers for specific format
-Serialbench.available_serializers(:json).each do |serializer_class|
-  serializer = serializer_class.new
-  puts "JSON: #{serializer.name} v#{serializer.version}"
-end
-----
 
-== Benchmark categories
+== Configuration Files
 
-=== Parsing performance
+=== Environment configuration
 
-Measures the time required to parse serialized data into Ruby objects.
+Environment configuration files define how benchmarks are executed in different runtime environments.
 
-* **Small files**: ~1KB configuration-style documents
-* **Medium files**: ~1MB API responses with 1,000 records
-* **Large files**: ~10MB data exports with 10,000 records
-
-=== Generation performance
+.Environment configuration for Docker (`config/environments/docker-ruby-3.4.yml`)
+[source,yaml]
+----
+---
+name: docker-ruby-3.4
+kind: docker
+created_at: '2025-06-13T15:18:43+08:00'
+ruby_build_tag: "3.4.1"
+description: Docker environment for Ruby 3.4 benchmarks
+docker:
+  image: 'ruby:3.4-slim'
+  dockerfile: '../../docker/Dockerfile.ubuntu'
+----
 
-Tests how quickly libraries can convert Ruby objects into serialized strings.
+.Environment configuration for ASDF (`config/environments/asdf-ruby-3.3.yml`)
+[source,yaml]
+----
+---
+name: ruby-332-asdf
+kind: asdf
+created_at: '2025-06-12T22:53:24+08:00'
+ruby_build_tag: 3.3.2
+description: ASDF environment
+asdf:
+  auto_install: true
+----
 
-=== Streaming performance
+=== Benchmark configuration
 
-Evaluates streaming event-based parsing performance for libraries that support it, which processes data sequentially and is memory-efficient for large files.
+Benchmark configuration files control what tests to run and how to run them.
 
-=== Memory usage analysis
+.Short configuration (CI-friendly) (`config/benchmarks/short.yml`)
+[source,yaml]
+----
+name: short-benchmark
 
-Profiles memory allocation and retention during serialization operations using the `memory_profiler` gem.
+data_sizes:
+- small
 
-== Output and reports
+formats:
+- xml
+- json
+- yaml
+- toml
 
-=== Generated files
+iterations:
+  small: 5
+  medium: 2
+  large: 1
 
-Running benchmarks creates the following output structure:
+operations:
+- parse
+- generate
+- streaming
 
-[source]
+warmup: 2
 ----
-results/
-├── reports/
-│   ├── benchmark_report.html    # Main HTML report
-│   └── benchmark_report.adoc    # AsciiDoc source
-├── charts/
-│   ├── parsing_performance.svg
-│   ├── generation_performance.svg
-│   ├── streaming_performance.svg
-│   ├── memory_usage_comparison.svg
-│   └── format_comparison.svg
-├── data/
-│   ├── results.json             # Raw benchmark data
-│   └── results.csv              # CSV export
-└── assets/
-    └── css/
-        └── benchmark_report.css # Report styling
-----
-
-=== Report features
-
-* **Multi-format comparison**: Compare XML, JSON, and TOML performance
-* **Interactive charts**: SVG-based performance visualizations
-* **Comparative analysis**: Side-by-side library comparisons
-* **Performance rankings**: Fastest to slowest for each category
-* **Memory profiling**: Detailed memory allocation analysis
-* **Feature matrix**: Capability comparison across libraries
-* **Recommendations**: Use-case specific library suggestions
-* **Environment details**: Ruby version, platform, and library versions
-
-=== Sample output
 
-[source]
+.Full configuration (Comprehensive) (`config/benchmarks/full.yml`)
+[source,yaml]
 ----
-Serialbench - Comprehensive Serialization Performance Tests
-===========================================================
-Environment: Ruby 3.3.2 on arm64-darwin23
-Timestamp: 2024-01-15T10:30:00Z
-
-Available serializers: rexml, json, oj, toml-rb
-Test formats: xml, json, toml
-Test data sizes: small, medium, large
+name: full-benchmark
 
-Parsing Performance:
-  Small files:
-    JSON/oj: 0.08ms
-    JSON/json: 0.12ms
-    XML/rexml: 0.45ms
-    TOML/toml-rb: 0.52ms
+data_sizes:
+- small
+- medium
+- large
 
-  Medium files:
-    JSON/oj: 8.23ms
-    JSON/json: 12.67ms
-    XML/rexml: 28.45ms
-    TOML/toml-rb: 35.21ms
-----
+formats:
+- xml
+- json
+- yaml
+- toml
 
-== Methodology
+iterations:
+  small: 20
+  medium: 5
+  large: 2
 
-=== Performance measurement
+operations:
+- parse
+- generate
+- streaming
+- memory
 
-* Each test runs multiple iterations with warmup iterations
-* Memory profiling uses 10 iterations to reduce noise
-* Results show average performance across all iterations
-* Benchmarks use Ruby's `Benchmark.realtime` for precise timing
+warmup: 3
+----
 
-=== Test data
+== Results structure
 
-==== Synthetic datasets
+=== Individual run results
 
-The benchmark suite uses carefully crafted synthetic data that represents common real-world scenarios:
+Results are stored in a structured directory format, with each run containing
+raw benchmark data and execution logs.
 
-* **Configuration files**: Small, nested structures typical of application settings
-* **API responses**: Medium-sized documents with repeated record structures
-* **Data exports**: Large documents with extensive hierarchical data
+The directory is located at `results/runs/{name}/`, where `{name}` is the name
+of the environment used for the benchmark.
 
-==== Multi-format consistency
+[source]
+----
+results/runs/docker-ruby-33-results/
+├── results.yaml                    # Raw benchmark data
+└── benchmark.log                   # Execution log
+----
 
-* Equivalent data structures across XML, JSON, and TOML formats
-* Consistent complexity and nesting levels
-* Representative of real-world usage patterns
+=== ResultSet structure
 
-=== Statistical considerations
+ResultSets aggregate multiple benchmark runs for comparison. They are stored in
+a structured directory format at `results/sets/{name}/`, where `{name}` is the
+name of the result set.
 
-* Multiple iterations reduce timing variance
-* Warmup iterations eliminate JIT compilation effects
-* Memory measurements account for garbage collection
-* Results include both absolute and relative performance metrics
+[source]
+----
+results/sets/ruby-version-comparison/
+└── resultset.yml                  # Result set configuration
+----
 
-== Library comparison matrix
+== Benchmark categories
 
-[cols="1,1,1,1,1,1,1"]
-|===
-|Format |Library |Parsing |Generation |Streaming |Memory |Features
-
-|XML |REXML |⭐⭐ |⭐⭐ |⭐⭐⭐ |⭐⭐ |Built-in
-|XML |Ox |⭐⭐⭐⭐⭐ |⭐⭐⭐⭐⭐ |⭐⭐⭐⭐ |⭐⭐⭐⭐⭐ |High-performance
-|XML |Nokogiri |⭐⭐⭐⭐ |⭐⭐⭐⭐ |⭐⭐⭐⭐ |⭐⭐⭐⭐ |Feature-rich
-|XML |LibXML |⭐⭐⭐⭐⭐ |⭐⭐⭐⭐ |⭐⭐⭐⭐ |⭐⭐⭐⭐⭐ |High-performance
-|XML |Oga |⭐⭐ |⭐⭐ |⭐⭐⭐ |⭐⭐ |Pure Ruby
-|JSON |JSON |⭐⭐⭐ |⭐⭐⭐ |❌ |⭐⭐⭐ |Built-in
-|JSON |Oj |⭐⭐⭐⭐⭐ |⭐⭐⭐⭐⭐ |⭐⭐⭐⭐ |⭐⭐⭐⭐⭐ |High-performance
-|JSON |YAJL |⭐⭐⭐⭐ |⭐⭐⭐ |⭐⭐⭐⭐ |⭐⭐⭐⭐ |Streaming
-|TOML |TOML-RB |⭐⭐⭐ |⭐⭐⭐ |❌ |⭐⭐⭐ |Standard
-|TOML |Tomlib |⭐⭐⭐⭐⭐ |⭐⭐⭐⭐ |❌ |⭐⭐⭐⭐⭐ |High-performance
-|===
+=== Parsing performance
 
-_Performance ratings: ⭐⭐⭐⭐⭐ Excellent, ⭐⭐⭐⭐ Good, ⭐⭐⭐ Average, ⭐⭐ Below average, ⭐ Poor, ❌ Not supported_
+Measures the time required to parse serialized data into Ruby objects.
 
-== Recommendations
+* **Small files**: ~1KB configuration-style documents
+* **Medium files**: ~1MB API responses with 1,000 records
+* **Large files**: ~10MB data exports with 10,000 records
 
-=== For high-performance JSON applications
+=== Generation performance
 
-**Oj** is recommended for applications where JSON parsing/generation speed is critical. It consistently outperforms the built-in JSON library.
+Tests how quickly libraries can convert Ruby objects into serialized strings.
 
-=== For configuration files
+=== Streaming performance
 
-**TOML** provides human-readable configuration with good parsing performance. **JSON** is faster but less readable for configuration.
+Evaluates streaming event-based parsing performance for libraries that support
+it, which processes data sequentially and is memory-efficient for large files.
 
-=== For data interchange
+=== Memory usage analysis
 
-**JSON** offers the best balance of performance, compatibility, and tooling support across different systems.
+Profiles memory allocation and retention during serialization operations using
+the `memory_profiler` gem.
 
-=== For document processing
+== Interactive Dashboard Features
 
-**XML** with **REXML** provides built-in support, though performance is lower than JSON alternatives.
+The generated HTML sites provide comprehensive interactive dashboards with:
 
-=== For memory-constrained environments
+=== Navigation and Filtering
+* **Format tabs**: Dedicated views for XML, JSON, YAML, and TOML
+* **Operation sections**: Parsing, generation, streaming, and memory usage
+* **Dynamic filtering**: Platform, Ruby version, and environment selection
+* **Real-time updates**: Charts update instantly based on filter selections
 
-**Oj** demonstrates superior memory efficiency. For large file processing, streaming approaches are recommended where available.
+=== Visualization Capabilities
+* **Chart.js integration**: Interactive performance charts with hover details
+* **Multi-scale handling**: Automatic Y-axis scaling for different performance ranges
+* **Color-coded data**: Consistent color schemes across serializers and environments
+* **Responsive design**: Optimized for desktop and mobile viewing
 
-=== For minimal dependencies
+=== User Experience
+* **Theme toggle**: Light and dark mode with persistent preferences
+* **Keyboard navigation**: Full accessibility support
+* **Fast loading**: Optimized JavaScript for quick dashboard initialization
+* **Export capabilities**: JSON data export for further analysis
 
-**JSON** and **REXML** are included with Ruby and require no additional gems, making them suitable for environments with strict dependency constraints.
 
 == Development
 
-=== Running tests
+=== Running Tests
 
-[source,shell]
+[source]
 ----
 $ bundle exec rake
 $ bundle exec rspec
 ----
 
-=== Contributing
+=== Adding a new serializers
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin feature/my-new-feature`)
-5. Create a new Pull Request
+To add support for additional serialization libraries:
 
-=== Adding new serializers
+. Create a new serializer class in `lib/serialbench/serializers/{format}/`
+. Inherit from the appropriate base class (`BaseXmlSerializer`, `BaseJsonSerializer`, etc.)
+. Implement the required methods: `parse`, `generate`, `name`, `version`
+. Add the serializer to the registry in `lib/serialbench/serializers.rb`
+. Update documentation and tests
 
-To add support for additional serialization libraries:
+=== Contributing
 
-1. Create a new serializer class in `lib/serialbench/serializers/{format}/`
-2. Inherit from the appropriate base class (`BaseXmlSerializer`, `BaseJsonSerializer`, etc.)
-3. Implement the required methods: `parse`, `generate`, `name`, `version`
-4. Add the serializer to the registry in `lib/serialbench/serializers.rb`
-5. Update documentation and tests
+. Fork the repository
+. Create your feature branch (`git checkout -b feature/my-new-feature`)
+. Commit your changes (`git commit -am 'Add some feature'`)
+. Push to the branch (`git push origin feature/my-new-feature`)
+. Create a new Pull Request
 
-==== Example: Adding a new JSON serializer
 
-[source,ruby]
-----
-# lib/serialbench/serializers/json/yajl_serializer.rb
-class YajlSerializer < BaseJsonSerializer
-  def available?
-    require_library('yajl')
-  end
+== Known issues
 
-  def name
-    'yajl'
-  end
+=== Syck YAML serializer segmentation faults
 
-  def version
-    require 'yajl'
-    Yajl::VERSION
-  end
+The Syck YAML serializer at version 1.5+ is known to cause segmentation faults
+on Ruby 3.1 and later versions. Serialbench automatically detects this
+problematic configuration and:
 
-  def parse(json_string)
-    require 'yajl'
-    Yajl::Parser.parse(json_string)
-  end
+* Displays a warning message when Syck is detected on Ruby 3.1+
+* Skips Syck benchmarks to prevent crashes
+* Continues with other YAML serializers (Psych)
 
-  def generate(object, options = {})
-    require 'yajl'
-    Yajl::Encoder.encode(object)
-  end
-end
-----
+=== Syck overrides YAML constant
 
-== Architecture
+On occasion after Syck is loaded, the constant `YAML` may be redefined to
+`Syck`, which can cause issues in other parts of the codebase. This can cause
+YAML output to fail when using libraries that expect `YAML` to have the
+`Psych` API.
 
-=== Serializer hierarchy
+In `benchmark_cli.rb` there is therefore such code to ensure that
+`YAML` is defined as `Psych` when writing to file is needed:
 
-[source]
+[source,ruby]
 ----
-BaseSerializer
-├── BaseXmlSerializer
-│   └── RexmlSerializer
-├── BaseJsonSerializer
-│   ├── JsonSerializer
-│   └── OjSerializer
-└── BaseTomlSerializer
-    └── TomlRbSerializer
+# Restore YAML to use Psych for output, otherwise lutaml-model's to_yaml
+# will have no output
+Object.const_set(:YAML, Psych)
 ----
 
-=== Key components
-
-* **Serializers**: Individual library implementations
-* **BenchmarkRunner**: Orchestrates benchmark execution
-* **ResultFormatter**: Formats and displays results
-* **ReportGenerator**: Creates HTML/AsciiDoc reports
-* **ChartGenerator**: Creates performance visualizations
-* **MemoryProfiler**: Analyzes memory usage patterns
-
-== Research and references
-
-This benchmarking suite was developed based on research from:
-
-* https://www.ohler.com/dev/xml_with_ruby/xml_with_ruby.html[XML with Ruby performance analysis]
-* https://gist.github.com/danneu/3977120[Ruby XML parser comparison]
-* https://gist.github.com/adilosa/d4277dc1c683da91990515352ffe5420[XML parsing benchmarks]
 
-== Copyright
+== License and copyright
 
-This gem is developed, maintained and funded by
-https://www.ribose.com[Ribose Inc.]
+Copyright Ribose.
 
-== License
+This gem is developed, maintained and funded by https://www.ribose.com[Ribose]
 
 The gem is available as open source under the terms of the
 https://opensource.org/licenses/BSD-2-Clause[2-Clause BSD License].