fontisan 0.2.8 → 0.2.10

data/docs/COLLECTION_VALIDATION.adoc

@@ -0,0 +1,143 @@
+= Font Collection Validation
+
+== General
+
+Fontisan provides validation support for font collections (TTC, OTC, dfont),
+enabling quality assurance across multiple fonts in a single file.
+
+Collection validation ensures all fonts in a collection meet quality standards
+while providing per-font and aggregate reporting.
+
+== Collection validation output
+
+When validating a collection, Fontisan displays:
+
+* *Collection header* - Path, type, and number of fonts
+* *Summary* - Total errors, warnings, and info across all fonts
+* *Per-font sections* - Individual validation results for each font with:
+  ** Font index and name
+  ** Font path in `collection.ttc:index` format
+  ** Individual font status (VALID/INVALID/VALID_WITH_WARNINGS)
+  ** Font-specific errors and warnings
+
+.Using the CLI to validate a font collection
+[example]
+====
+[source,shell]
+----
+$ fontisan validate /path/to/font.ttc
+
+Collection: /path/to/font.ttc
+Type: TTC
+Fonts: 4
+
+Summary:
+  Total Errors: 14
+  Total Warnings: 8
+  Total Info: 0
+
+=== Font 0: Lucida Grande ===
+Font: /path/to/font.ttc:0
+Status: INVALID
+
+Errors:
+  name_table.family_name_present - Family name is empty
+  head_table.valid_magic - Invalid magic number
+
+Warnings:
+  os2_table.valid_version - Version 5 requires Windows 10+
+
+=== Font 1: Lucida Grande Bold ===
+Font: /path/to/font.ttc:1
+Status: VALID
+...
+----
+====
+
+== Validation profiles with collections
+
+All validation profiles work with font collections. The selected profile determines:
+
+* **Which tables are loaded** - metadata vs full mode
+* **Which checks are performed** - number and type of validations
+* **Performance characteristics** - indexability is ~5x faster than production
+
+.Using validation profiles with collections
+[example]
+====
+[source,shell]
+----
+# Quick validation for indexing (metadata mode, 8 checks, ~5x faster)
+$ fontisan validate /path/to/font.ttc -t indexability
+
+# Comprehensive validation (full mode, 37 checks)
+$ fontisan validate /path/to/font.ttc -t production
+
+# Web font readiness validation
+$ fontisan validate /path/to/font.ttc -t web
+----
+====
+
+== Collection validation exit codes
+
+For collections, the validation command uses the "worst" status across all fonts:
+
+* **0** = All fonts valid
+* **2** = Any font has fatal errors
+* **3** = Any font has errors (and no fatal)
+* **4** = Any font has warnings (and no errors)
+* **5** = Any font has info issues (and no errors or warnings)
+
+.Checking collection validation exit codes
+[example]
+====
+[source,shell]
+----
+$ fontisan validate font.ttc -S -R
+
+Collection: font.ttc
+Type: TTC
+Fonts: 3
+
+Summary:
+  Total Errors: 2
+  Total Warnings: 5
+
+$ echo $?
+3  # Exit code 3 indicates errors found
+----
+====
+
+== Ruby API for collection validation
+
+.Using the Ruby API for collection validation
+[example]
+====
+[source,ruby]
+----
+require 'fontisan'
+
+# Validate collection
+report = Fontisan.validate('font.ttc', profile: :production)
+
+# Check overall status
+puts report.overall_status  # "valid", "valid_with_warnings", "invalid"
+
+# Access per-font reports
+report.font_reports.each_with_index do |font_report, i|
+  puts "Font #{i}: #{font_report.font_name}"
+  puts "  Status: #{font_report.report.status}"
+  puts "  Errors: #{font_report.report.summary.errors}"
+  puts "  Warnings: #{font_report.report.summary.warnings}"
+end
+
+# Get aggregate statistics
+puts "Total fonts: #{report.num_fonts}"
+
+# Count valid/invalid fonts (requires iteration)
+valid_count = report.font_reports.count { |fr| fr.report.valid? }
+invalid_count = report.font_reports.count { |fr| !fr.report.valid? }
+puts "Valid fonts: #{valid_count}"
+puts "Invalid fonts: #{invalid_count}"
+----
+====

data/docs/COLOR_FONTS.adoc

@@ -0,0 +1,127 @@
+= Color Font Support
+
+== General
+
+Fontisan provides support for color fonts through multiple formats:
+
+* **COLR/CPAL** - OpenType color layered glyphs (SVG-like layering in font)
+* **sbix** - Apple color bitmap glyphs (embedded raster images)
+* **SVG** - OpenType SVG color glyphs (embedded SVG vector graphics)
+
+Color fonts enable rich typography with gradients, images, and artistic effects
+beyond standard outline fonts.
+
+=== COLR/CPAL color layered glyphs
+
+The COLR table defines color layers using base glyphs and paint layers,
+with the CPAL table defining color palettes.
+
+[source,shell]
+----
+$ fontisan tables FONT.ttf --format yaml | grep -A 50 "tag: COLR"
+----
+
+.COLR table structure
+[example]
+====
+[source,yaml]
+----
+---
+tag: COLR
+version: 0
+num_base_glyphs: 15
+num_layers: 47
+num_palettes: 1
+color_records: 8
+
+Base glyphs:
+  - base_glyph: emoji_smile
+    layers:
+      - glyph: emoji_smile_layer0
+        palette_index: 1
+        color_index: 0
+      - glyph: emoji_smile_layer1
+        palette_index: 1
+        color_index: 1
+----
+====
+
+=== sbix color bitmap glyphs
+
+Apple's sbix table embeds raster images (PNG, JPG) for color glyphs.
+Each glyph can have multiple bitmap strikes at different sizes.
+
+[source,shell]
+----
+$ fontisan tables FONT.ttf | grep -A 20 "tag: sbix"
+----
+
+.sbix structure
+[example]
+====
+[source,text]
+----
+  sbix        245892 bytes  (offset: 542992, checksum: 0x12345678)
+
+Strikes:
+  Strike 0: 72 PPI
+    Bitmaps: 150 glyphs
+    Format: PNG
+    Glyph 1 (emoji_smile): 128x128 pixels, 8.2 KB
+    Glyph 2 (emoji_heart): 128x128 pixels, 7.8 KB
+----
+====
+
+=== SVG table color glyphs
+
+The SVG table contains inline SVG graphics for color glyphs, supporting
+gradients, transparency, and complex vector artwork.
+
+[source,shell]
+----
+$ fontisan dump-table FONT.ttf SVG > svg_content.svg
+----
+
+.SVG table structure
+[example]
+====
+[source,text]
+----
+  svg         45678 bytes  (offset: 788760, checksum: 0xABCDEF01)
+
+SVG Documents: 12
+  Glyph 1 (emoji_flag_us): 1.2 KB
+  Glyph 2 (emoji_heart): 0.8 KB
+  Glyph 3 (gradient_icon): 2.1 KB
+----
+====
+
+=== Ruby API for color fonts
+
+Access color font data through the Ruby API.
+
+[source,ruby]
+----
+require 'fontisan'
+
+font = Fontisan::FontLoader.load('color_font.ttf')
+
+# Access COLR/CPAL data
+colr = font.table('COLR')
+cpal = font.table('CPAL')
+
+puts "Base glyphs: #{colr.num_base_glyph_records}"
+puts "Palettes: #{cpal.num_palettes}"
+
+# Access sbix strikes
+sbix = font.table('sbix')
+sbix.strikes.each do |strike|
+  puts "Strike: #{strike[:ppi]} PPI, #{strike[:num_glyphs]} glyphs"
+end
+
+# Access SVG data
+svg = font.table('SVG')
+svg.document_records.each do |record|
+  puts "Glyphs #{record.start_glyph_id}-#{record.end_glyph_id}: #{record.svg_doc_length} bytes"
+end
+----

data/docs/DOCUMENTATION_SUMMARY.md

@@ -0,0 +1,141 @@
+# Fontisan Documentation Summary
+
+This document provides an overview of all Fontisan documentation files and their purpose.
+
+## Main Documentation
+
+### README.adoc
+Primary user guide and reference documentation for Fontisan.
+
+## Feature Guides
+
+### Font Hinting
+- **File**: `docs/FONT_HINTING.adoc`
+- **Purpose**: Documentation for font hinting features in Fontisan
+- **Topics**: TrueType and PostScript hinting, hint extraction and application
+
+### Variable Font Operations
+- **File**: `docs/VARIABLE_FONT_OPERATIONS.adoc`
+- **Purpose**: Guide for working with variable fonts
+- **Topics**: Instance generation, axis manipulation, variation preservation
+
+### TTC Migration Guide
+- **File**: `docs/EXTRACT_TTC_MIGRATION.md`
+- **Purpose**: Migration guide for users of the `extract-ttc` gem
+- **Topics**: Moving from extract-ttc to Fontisan pack/unpack commands
+
+### Web Font Formats
+- **File**: `docs/WOFF_WOFF2_FORMATS.adoc`
+- **Purpose**: Documentation for WOFF and WOFF2 web font formats
+- **Topics**: Conversion to/from WOFF/WOFF2, web optimization
+
+### Color Fonts
+- **File**: `docs/COLOR_FONTS.adoc`
+- **Purpose**: Guide for color font formats
+- **Topics**: COLR/CPAL, SVG-in-OpenType, sbix color fonts
+
+### Validation
+- **File**: `docs/VALIDATION.adoc`
+- **Purpose**: Font validation framework documentation
+- **Topics**: Validation profiles, quality checks, OpenType spec compliance
+
+### Apple Legacy Fonts
+- **File**: `docs/APPLE_LEGACY_FONTS.adoc`
+- **Purpose**: Documentation for Apple legacy font formats
+- **Topics**: dfont format, Mac suitcase fonts
+
+### Collection Validation
+- **File**: `docs/COLLECTION_VALIDATION.adoc`
+- **Purpose**: Guide for validating font collections (TTC/OTC/dfont)
+- **Topics**: Collection-specific validation, profile selection
+
+## CLI Commands Reference
+
+Fontisan provides the following CLI commands:
+
+| Command | Purpose |
+|---------|---------|
+| `info` | Display font information |
+| `ls` | List contents (fonts in collection or font summary) |
+| `tables` | List OpenType tables |
+| `glyphs` | List glyph names |
+| `unicode` | List Unicode to glyph mappings |
+| `variable` | Display variable font information |
+| `optical-size` | Display optical size information |
+| `scripts` | List supported scripts from GSUB/GPOS tables |
+| `features` | List GSUB/GPOS features |
+| `subset` | Subset a font to specific glyphs |
+| `convert` | Convert font to different format |
+| `instance` | Generate static font instance from variable font |
+| `pack` | Pack multiple fonts into TTC/OTC collection |
+| `unpack` | Unpack fonts from TTC/OTC collection |
+| `validate` | Validate font file |
+| `export` | Export font to TTX/YAML/JSON format |
+| `dump-table` | Dump raw table data to stdout |
+| `version` | Display version information |
+
+## Ruby API Reference
+
+### Fontisan Module Methods
+
+#### `Fontisan.info(path, brief: false, font_index: 0)`
+Get font information. Supports both full and brief modes.
+
+- **Parameters**:
+  - `path` (String): Path to font file
+  - `brief` (Boolean): Use brief mode for fast identification (default: false)
+  - `font_index` (Integer): Index for TTC/OTC files (default: 0)
+- **Returns**: `Models::FontInfo`, `Models::CollectionInfo`, or `Models::CollectionBriefInfo`
+- **Example**:
+  ```ruby
+  info = Fontisan.info("font.ttf", brief: true)
+  puts info.family_name
+  ```
+
+#### `Fontisan.validate(path, profile: :default, options: {})`
+Validate a font file using specified profile.
+
+- **Parameters**:
+  - `path` (String): Path to font file
+  - `profile` (Symbol/String): Validation profile (default: :default)
+  - `options` (Hash): Additional validation options
+- **Available Profiles**:
+  - `:indexability` - Fast validation for font discovery
+  - `:usability` - Basic usability for installation
+  - `:production` - Comprehensive quality checks (default)
+  - `:web` - Web embedding and optimization
+  - `:spec_compliance` - Full OpenType spec compliance
+  - `:default` - Alias for production profile
+- **Returns**: `Models::ValidationReport`
+- **Example**:
+  ```ruby
+  report = Fontisan.validate("font.ttf", profile: :web)
+  puts "Errors: #{report.summary.errors}"
+  ```
+
+### Fontisan::FontLoader
+
+Module for loading fonts in different modes.
+
+- **Methods**:
+  - `load(path, mode: :full)` - Load a font file
+- **Loading Modes**:
+  - `:full` - Load all tables
+  - `:metadata` - Load only metadata tables (name, head, hhea, maxp, OS/2, post)
+  - `:tables` - Load specific tables only
+  - `:structure` - Load structure tables only
+
+## Verification
+
+Documentation examples are verified by `spec/documentation_examples_spec.rb`.
+
+This spec ensures that:
+1. All CLI commands referenced in documentation exist
+2. All Ruby API methods are available
+3. All documentation files are present
+4. Command examples reference valid commands
+
+Run verification with:
+```bash
+bundle exec rspec spec/documentation_examples_spec.rb -v
+```

data/docs/FONT_HINTING.adoc

@@ -541,9 +541,12 @@ The hint system has comprehensive test coverage:
 * **Total Tests**: 306 (100% passing)
 * **Generator Tests**: 45
 * **Validator Tests**: 48
+* **Applier Tests**: 87 (PostScript: 63, TrueType: 24)
+* **Extractor Tests**: 23 (PostScript: 11, TrueType: 12)
+* **Converter Tests**: 29
 * **Round-Trip Tests**: 16
+* **Integration Tests**: 28 (Conversion: 11, Application: 17)
 * **Analyzer Tests**: 30
-* **Integration Tests**: 167
 
 Test files:
 
@@ -552,7 +555,12 @@ Test files:
 * link:../spec/fontisan/hints/hint_validator_spec.rb[hint_validator_spec.rb]
 * link:../spec/fontisan/hints/hint_round_trip_spec.rb[hint_round_trip_spec.rb]
 * link:../spec/fontisan/hints/hint_converter_spec.rb[hint_converter_spec.rb]
+* link:../spec/fontisan/hints/postscript_hint_applier_spec.rb[postscript_hint_applier_spec.rb]
+* link:../spec/fontisan/hints/postscript_hint_extractor_spec.rb[postscript_hint_extractor_spec.rb]
+* link:../spec/fontisan/hints/truetype_hint_applier_spec.rb[truetype_hint_applier_spec.rb]
+* link:../spec/fontisan/hints/truetype_hint_extractor_spec.rb[truetype_hint_extractor_spec.rb]
 * link:../spec/fontisan/hints/hint_conversion_integration_spec.rb[hint_conversion_integration_spec.rb]
+* link:../spec/fontisan/hints/hint_application_integration_spec.rb[hint_application_integration_spec.rb]
 
 == References
 

data/docs/VALIDATION.adoc

@@ -0,0 +1,254 @@
+= Font Validation Framework
+
+== General
+
+Fontisan provides a comprehensive validation framework for ensuring font quality,
+structural integrity, and compliance with OpenType specifications.
+
+The framework uses a declarative DSL for defining validation checks and supports
+multiple validation profiles for different use cases.
+
+== Validation profiles
+
+Fontisan includes predefined validation profiles:
+
+`indexability`:: Fast font discovery and indexing (8 checks, metadata-only, ~5x faster)
+
+`usability`:: Font installation compatibility (26 checks, macOS Font Book focused)
+
+`production`:: Comprehensive production quality (37 checks, OpenType spec compliance - default)
+
+`web`:: Web font embedding readiness (18 checks for web deployment)
+
+`spec_compliance`:: Full OpenType specification compliance (detailed analysis mode)
+
+[source,shell]
+----
+$ fontisan validate --list
+Available validation profiles:
+  indexability         - Fast validation for font discovery and indexing
+  usability            - Basic usability for installation
+  production           - Comprehensive quality checks
+  web                  - Web embedding and optimization
+  spec_compliance      - Full OpenType spec compliance
+  default              - Default validation profile (alias for production)
+----
+
+== Command-line validation
+
+.Validate with default profile
+[example]
+====
+[source,shell]
+----
+$ fontisan validate font.ttf
+
+Font: font.ttf
+Status: VALID
+
+Summary:
+  Checks performed: 37
+  Passed: 37
+  Failed: 0
+
+Errors: 0
+Warnings: 0
+Info: 0
+----
+====
+
+.Validate for web use with summary
+[example]
+====
+[source,shell]
+----
+$ fontisan validate font.ttf -t web -S
+
+Font: font.ttf
+Status: VALID
+
+Summary:
+  Checks performed: 18
+  Passed: 17
+  Failed: 1
+
+Errors: 1
+Warnings: 0
+
+Failed checks:
+  web_font_tables      - Missing required GSUB table
+----
+====
+
+.Validation with table format output
+[example]
+====
+[source,shell]
+----
+$ fontisan validate font.ttf -T
+
+CHECK_ID                    | STATUS | SEVERITY | TABLE
+------------------------------------------------------------
+required_tables             | PASS   | error    | N/A
+name_version                | PASS   | error    | name
+family_name                 | PASS   | error    | name
+----
+====
+====
+
+== Ruby API usage
+
+=== Using predefined profiles
+
+[source,ruby]
+----
+require 'fontisan'
+
+# Validate with default profile (production)
+report = Fontisan.validate('font.ttf')
+puts report.valid?  # => true or false
+
+# Validate with specific profile
+report = Fontisan.validate('font.ttf', profile: :web)
+puts "Errors: #{report.summary.errors}"
+puts "Warnings: #{report.summary.warnings}"
+
+# Check validation status
+if report.valid?
+  puts "Font is valid for web use!"
+else
+  puts "Font has #{report.summary.errors} errors"
+end
+----
+
+=== Query validation results
+
+[source,ruby]
+----
+report = Fontisan.validate('font.ttf', profile: :production)
+
+# Get issues by severity
+fatal_issues = report.fatal_errors
+error_issues = report.errors_only
+warning_issues = report.warnings_only
+info_issues = report.info_only
+
+# Get issues by category
+table_issues = report.issues_by_category('table_validation')
+
+# Get check results
+failed_ids = report.failed_check_ids
+pass_rate = report.pass_rate
+
+# Export to different formats
+yaml_output = report.to_yaml
+json_output = report.to_json
+summary = report.to_summary  # "2 errors, 3 warnings, 0 info"
+----
+
+== Creating custom validators
+
+=== General
+
+Custom validators inherit from `Fontisan::Validators::Validator` and define
+validation logic using the DSL.
+
+The DSL provides 6 check methods:
+
+* `check_table` - Validate table-level properties
+* `check_field` - Validate specific field values
+* `check_structure` - Validate font structure and relationships
+* `check_usability` - Validate usability and best practices
+* `check_instructions` - Validate TrueType instructions/hinting
+* `check_glyphs` - Validate individual glyphs
+
+.Creating a custom validator
+[example]
+====
+[source,ruby]
+----
+require 'fontisan/validators/validator'
+
+class MyFontValidator < Fontisan::Validators::Validator
+  private
+
+  def define_checks
+    # Check name table
+    check_table :name_validation, 'name', severity: :error do |table|
+      table.valid_version? &&
+        table.valid_encoding_heuristics? &&
+        table.family_name_present? &&
+        table.postscript_name_valid?
+    end
+
+    # Check head table
+    check_table :head_validation, 'head', severity: :error do |table|
+      table.valid_magic? &&
+        table.valid_version? &&
+        table.valid_units_per_em?
+    end
+
+    # Check structure
+    check_structure :required_tables, severity: :error do |font|
+      %w[name head maxp hhea].all? { |tag| !font.table(tag).nil? }
+    end
+  end
+end
+
+# Use the validator
+font = Fontisan::FontLoader.load('font.ttf')
+validator = MyFontValidator.new
+report = validator.validate(font)
+
+puts report.valid?                           # => true/false
+puts report.summary.errors                   # => number of errors
+puts report.summary.warnings                 # => number of warnings
+----
+====
+
+== Validation helpers
+
+The validation framework provides 56 helper methods across 8 core OpenType
+tables. Each helper returns a boolean indicating whether the validation passed.
+
+.Name table helpers:
+[example]
+====
+[source,ruby]
+----
+class MyValidator < Fontisan::Validators::Validator
+  private
+
+  def define_checks
+    check_table :name_validation, 'name', severity: :error do |table|
+      table.valid_version? &&
+        table.valid_encoding_heuristics? &&
+        table.family_name_present? &&
+        table.postscript_name_valid?
+    end
+  end
+end
+----
+====
+
+.Head table helpers:
+[example]
+====
+[source,ruby]
+----
+class MyValidator < Fontisan::Validators::Validator
+  private
+
+  def define_checks
+    check_table :head_validation, 'head', severity: :error do |table|
+      table.valid_magic? &&
+        table.valid_version? &&
+        table.valid_units_per_em? &&
+        table.valid_bounding_box? &&
+        table.valid_index_to_loc_format? &&
+        table.valid_glyph_data_format?
+    end
+  end
+end
+----
+====