fontisan 0.2.13 → 0.2.16

data/docs/guide/quick-start.md

@@ -0,0 +1,204 @@
+---
+title: Quick Start
+---
+
+# Quick Start
+
+This guide covers the most common Fontisan workflows.
+
+## Loading Fonts
+
+Fontisan automatically detects font formats:
+
+```ruby
+require 'fontisan'
+
+# TrueType
+font = Fontisan::FontLoader.load('font.ttf')
+
+# OpenType
+font = Fontisan::FontLoader.load('font.otf')
+
+# WOFF/WOFF2
+font = Fontisan::FontLoader.load('font.woff')
+font = Fontisan::FontLoader.load('font.woff2')
+
+# Type 1
+font = Fontisan::FontLoader.load('font.pfb')
+font = Fontisan::FontLoader.load('font.pfa')
+
+# Collections
+fonts = Fontisan::FontLoader.load('fonts.ttc')
+fonts = Fontisan::FontLoader.load('fonts.otc')
+```
+
+## Font Information
+
+### Basic Information
+
+```ruby
+font = Fontisan::FontLoader.load('font.ttf')
+
+# Access tables directly
+name_table = font.tables['name']
+head_table = font.tables['head']
+
+# Get family name
+family = name_table.family_name
+
+# Get style
+style = name_table.subfamily_name
+
+# Get metrics
+units_per_em = head_table.units_per_em
+```
+
+### Using CLI
+
+```bash
+# Get comprehensive info
+fontisan info font.ttf
+
+# Output in different formats
+fontisan info font.ttf --format yaml
+fontisan info font.ttf --format json
+```
+
+## Font Conversion
+
+### Basic Conversion
+
+```ruby
+# TTF to OTF
+Fontisan.convert('input.ttf', output_format: :otf)
+
+# OTF to WOFF2
+Fontisan.convert('input.otf', output_format: :woff2)
+
+# Type 1 to OTF
+Fontisan.convert('input.pfb', output_format: :otf)
+```
+
+### With Options
+
+```ruby
+options = Fontisan::ConversionOptions.new(
+  from: :ttf,
+  to: :otf,
+  opening: { autohint: true, convert_curves: true },
+  generating: { hinting_mode: 'auto' }
+)
+
+Fontisan.convert('input.ttf', output_format: :otf, options: options)
+```
+
+### Using CLI
+
+```bash
+# Basic conversion
+fontisan convert input.ttf --to otf --output output.otf
+
+# Show recommended options
+fontisan convert input.ttf --to otf --show-options
+
+# Use a preset
+fontisan convert font.pfb --to otf --preset type1_to_modern --output output.otf
+
+# With autohint
+fontisan convert input.ttf --to otf --autohint --hinting-mode auto --output output.otf
+```
+
+## Font Validation
+
+### Using Ruby API
+
+```ruby
+# Validate with default profile
+result = Fontisan::FontValidator.validate('font.ttf')
+
+# Validate with specific profile
+result = Fontisan::FontValidator.validate('font.ttf', profile: :google_fonts)
+
+# Check results
+if result.passed?
+  puts "✓ Font is valid"
+else
+  puts "✗ Validation failed:"
+  result.errors.each do |error|
+    puts "  - #{error.code}: #{error.message}"
+  end
+end
+```
+
+### Using CLI
+
+```bash
+# Validate with Google Fonts profile
+fontisan validate font.ttf --profile google_fonts
+
+# Validate with Microsoft profile
+fontisan validate font.ttf --profile microsoft
+
+# Validate multiple files
+fontisan validate fonts/*.ttf --profile production
+```
+
+## Working with Collections
+
+### List Fonts in Collection
+
+```bash
+fontisan ls fonts.ttc
+```
+
+### Extract Fonts from Collection
+
+```bash
+# Extract all fonts
+fontisan unpack fonts.ttc --output-dir ./extracted
+
+# Extract with format conversion
+fontisan unpack fonts.ttc --output-dir ./extracted --format otf
+```
+
+### Create Collection
+
+```bash
+# Pack fonts into TTC
+fontisan pack font1.ttf font2.ttf font3.ttf --output fonts.ttc
+
+# Pack with deduplication
+fontisan pack font1.ttf font2.ttf --output fonts.ttc --deduplicate
+```
+
+## Variable Fonts
+
+### Get Axis Information
+
+```ruby
+font = Fontisan::FontLoader.load('variable-font.ttf')
+fvar = font.tables['fvar']
+
+fvar.axes.each do |axis|
+  puts "#{axis.tag}: #{axis.min_value} - #{axis.max_value}"
+end
+```
+
+### Generate Instance
+
+```ruby
+# Generate static instance
+instance = Fontisan::Variation::InstanceGenerator.new(font).generate(
+  'wght' => 700,
+  'ital' => 1
+)
+
+Fontisan::FontWriter.write(instance, 'bold-italic.ttf')
+```
+
+## Next Steps
+
+- [Font Formats](/guide/formats/) — Detailed format documentation
+- [Conversion Guide](/guide/conversion/) — Advanced conversion options
+- [Validation](/guide/validation/) — Validation profiles and helpers
+- [CLI Reference](/guide/cli/) — Complete CLI documentation

data/docs/guide/type1.md

@@ -0,0 +1,58 @@
+---
+outline: [2, 3]
+---
+
+# Type 1 Fonts
+
+Fontisan provides comprehensive support for Adobe Type 1 fonts.
+
+## Overview
+
+Adobe Type 1 fonts are a legacy format based on PostScript outlines. Fontisan can read, validate, and convert these fonts to modern formats.
+
+## Reading Type 1 Fonts
+
+```ruby
+require 'fontisan'
+
+# Load a Type 1 font
+font = Fontisan::Type1.load('font.pfb')
+
+# Access font properties
+puts font.family_name
+puts font.full_name
+puts font.num_glyphs
+```
+
+## Converting Type 1 Fonts
+
+```ruby
+# Convert to TrueType
+Fontisan.convert('font.pfb', output_format: :ttf)
+
+# Convert to OpenType
+Fontisan.convert('font.pfb', output_format: :otf)
+
+# Convert to WOFF2
+Fontisan.convert('font.pfb', output_format: :woff2)
+```
+
+## Handling Encodings
+
+Type 1 fonts may use various encodings:
+
+```ruby
+font = Fontisan::Type1.load('font.pfb')
+
+# Get the font encoding
+puts font.encoding
+
+# List available glyphs
+font.glyphs.each do |glyph|
+  puts "#{glyph.name}: #{glyph.codepoint}"
+end
+```
+
+## Related
+
+- [Font Conversion](/guide/conversion) - General conversion guide

data/docs/guide/universal-outline.md

@@ -0,0 +1,151 @@
+---
+title: Universal Outline Model
+---
+
+# Universal Outline Model
+
+The Fontisan Universal Outline Model (UOM) provides a format-agnostic representation of glyph contours that enables seamless conversion between different font formats.
+
+## Overview
+
+The UOM is based on a self-stable algorithm for converting soft glyph contours to outline format. This architecture allows:
+
+- Importing glyphs from any font format (TrueType, OpenType, CFF)
+- Converting glyph elements between formats
+- Operating on outlines with transformations
+- Serialization and storage
+
+## Core Components
+
+### Locker
+
+The Locker is an object-oriented model for storing imported outlines and glyphs. Storage is based on monotonic spirals computed from 2D points and curves.
+
+**Features:**
+- Invisible conversion from TrueType, CFF OpenType, and ColorGlyph formats
+- Preserves original glyph geometry
+- Supports compound glyph decomposition
+
+### Translator
+
+The Translator is an object-oriented model for converting between PostScript CFF charsets.
+
+**Features:**
+- PostScript Type 2/3/composite encoding and decoding
+- CFF INDEX structure building
+- CFF DICT structure building
+- Charset conversion
+
+### ColorGlyph
+
+ColorGlyph provides support for layered CFF color glyphs with on-demand rasterization.
+
+**Features:**
+- Composite font support
+- Multi-layer color font representation
+- CFF fonts stacked on top of each other
+- Advanced color glyphs
+- Raster image support (PNG/JPG) combined with TrueType outlines
+
+## Universal Fonts
+
+Fontisan provides universal font capabilities:
+
+| Capability | Description |
+|------------|-------------|
+| Import | Import TrueType contours into UOM |
+| Operate | Transform, clean, improve, and render outlines |
+| Convert | Convert UOM contours to TTF/OTF |
+| Serialize | Save and share font structures |
+| Color Support | Work with advanced color fonts |
+
+## Universal Glyphs
+
+The universal glyph model enables:
+
+- Universal Outline Model (UOM) for TrueType contours and CFF color glyphs
+- Repository for custom fonts
+- Custom Unicode assignments and configuration
+- Outline import/export (TrueType and OTF/CFF)
+- Rendering for advanced font types
+- Universal layer stacking for color glyph combinations
+
+## Universal Color Layers
+
+Universal color layers support advanced color font operations:
+
+| Feature | Description |
+|---------|-------------|
+| Import | Import embedded TTF/OTF color layers |
+| Assemble | Assemble from individual TTF/OTF slices |
+| Manage | Advanced layer map management in TTF color fonts |
+| Blend | Advanced color layer blending style management |
+| Convert | Gray/Overprint/Color-Full image comps and layer conversion |
+| Raster | Smart vector combos from raster images |
+| PNG | Import and generate PNG block ruler layers |
+
+## Curve Conversion
+
+The UOM handles bidirectional curve conversion:
+
+- **TrueType → CFF**: Quadratic to cubic curve conversion
+- **CFF → TrueType**: Cubic to quadratic curve conversion
+- **CFF2 Support**: Variable font CFF2 outlines
+
+## Ruby API
+
+### Loading Outlines
+
+```ruby
+require 'fontisan'
+
+# Load font and access universal outlines
+font = Fontisan::FontLoader.load('font.ttf')
+
+# Access glyphs through universal model
+glyphs = font.glyphs
+
+glyphs.each do |glyph|
+  # Access universal outline representation
+  outline = glyph.universal_outline
+
+  # Get contour count
+  puts "Glyph #{glyph.name}: #{outline.contour_count} contours"
+
+  # Access points and curves
+  outline.contours.each do |contour|
+    contour.commands.each do |cmd|
+      case cmd.type
+      when :move_to
+        puts "  Move to #{cmd.x}, #{cmd.y}"
+      when :line_to
+        puts "  Line to #{cmd.x}, #{cmd.y}"
+      when :quad_to
+        puts "  Quadratic curve to #{cmd.x}, #{cmd.y}"
+      when :curve_to
+        puts "  Cubic curve to #{cmd.x}, #{cmd.y}"
+      end
+    end
+  end
+end
+```
+
+### Converting Outlines
+
+```ruby
+# Convert between curve types
+converter = Fontisan::Converters::CurveConverter.new
+
+# TrueType (quadratic) to CFF (cubic)
+cff_outlines = converter.quad_to_cubic(truetype_outlines)
+
+# CFF (cubic) to TrueType (quadratic)
+ttf_outlines = converter.cubic_to_quad(cff_outlines)
+```
+
+## Related Documentation
+
+- [Curve Converter API](/api/converters/curve-converter) — Curve conversion details
+- [Outline Converter API](/api/converters/outline-converter) — Full outline conversion
+- [Font Conversion Guide](/guide/conversion/) — Conversion workflows
+- [Color Fonts Guide](/guide/color-fonts/) — Color font support

data/docs/guide/validation/custom.md

@@ -0,0 +1,195 @@
+---
+title: Custom Validators
+---
+
+# Custom Validators
+
+Create custom validation rules using Fontisan's validation DSL.
+
+## Overview
+
+Custom validators inherit from `Fontisan::Validators::Validator` and define validation logic using the DSL.
+
+## DSL Methods
+
+The DSL provides 6 check methods:
+
+| Method | Description |
+|--------|-------------|
+| `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 Validator
+
+### Basic Structure
+
+```ruby
+require 'fontisan/validators/validator'
+
+class MyFontValidator < Fontisan::Validators::Validator
+  private
+
+  def define_checks
+    # Define your checks here
+  end
+end
+```
+
+### Table Validation
+
+```ruby
+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
+end
+```
+
+### Structure Validation
+
+```ruby
+def define_checks
+  check_structure :required_tables, severity: :error do |font|
+    %w[name head maxp hhea].all? { |tag| !font.table(tag).nil? }
+  end
+
+  check_structure :optional_tables, severity: :warning do |font|
+    # Check for recommended optional tables
+    %w[cmap hmtx].all? { |tag| !font.table(tag).nil? }
+  end
+end
+```
+
+### Field Validation
+
+```ruby
+def define_checks
+  check_field :units_per_em, 'head.units_per_em', severity: :error do |value|
+    [1000, 2048].include?(value)
+  end
+
+  check_field :font_revision, 'head.font_revision', severity: :warning do |value|
+    value > 0 && value < 100
+  end
+end
+```
+
+### Glyph Validation
+
+```ruby
+def define_checks
+  check_glyphs :glyph_bounds, severity: :warning do |glyph|
+    # Check if glyph has valid bounds
+    !glyph.bounds.nil? &&
+      glyph.bounds.min_x >= -10000 &&
+      glyph.bounds.max_x <= 10000
+  end
+end
+```
+
+## Severity Levels
+
+| Severity | Description |
+|----------|-------------|
+| `:fatal` | Critical error, font unusable |
+| `:error` | Error, font may not work correctly |
+| `:warning` | Warning, best practice violation |
+| `:info` | Informational, no impact |
+
+## Using Custom Validators
+
+```ruby
+# Load font
+font = Fontisan::FontLoader.load('font.ttf')
+
+# Create validator instance
+validator = MyFontValidator.new(font)
+
+# Run validation
+report = validator.validate
+
+# Check results
+if report.valid?
+  puts "Font is valid!"
+else
+  report.errors.each do |error|
+    puts "#{error.check_id}: #{error.message}"
+  end
+end
+```
+
+## Complete Example
+
+```ruby
+require 'fontisan/validators/validator'
+
+class WebFontValidator < Fontisan::Validators::Validator
+  private
+
+  def define_checks
+    # Required tables for web fonts
+    check_structure :web_required_tables, severity: :error do |font|
+      required = %w[name head maxp hhea cmap hmtx]
+      required.all? { |tag| !font.table(tag).nil? }
+    end
+
+    # Name records completeness
+    check_table :name_completeness, 'name', severity: :error do |table|
+      [
+        table.family_name_present?,
+        table.subfamily_name_present?,
+        table.unique_id_present?,
+        table.full_name_present?,
+        table.version_present?
+      ].all?
+    end
+
+    # UPM should be power of 2 for web
+    check_field :web_units_per_em, 'head.units_per_em', severity: :info do |value|
+      [256, 512, 1024, 2048, 4096].include?(value)
+    end
+
+    # Check for GSUB (recommended for web)
+    check_structure :web_gsub_presence, severity: :info do |font|
+      !font.table('GSUB').nil?
+    end
+  end
+end
+
+# Use the validator
+font = Fontisan::FontLoader.load('font.ttf')
+validator = WebFontValidator.new(font)
+report = validator.validate
+
+puts report.to_summary
+```
+
+## Integrating with Profiles
+
+Custom validators can be integrated into validation profiles:
+
+```ruby
+# Create a custom profile
+profile = Fontisan::Validators::ValidationProfile.new(
+  name: :my_custom,
+  validators: [MyFontValidator]
+)
+
+# Use the profile
+report = Fontisan.validate('font.ttf', profile: profile)
+```