fontisan 0.2.14 → 0.2.16

data/docs/guide/color-fonts/index.md

@@ -0,0 +1,140 @@
+---
+title: Color Fonts Overview
+---
+
+# Color Fonts Overview
+
+Fontisan supports multiple color font formats for modern typography.
+
+## Supported Formats
+
+| Format | Tables | Description |
+|--------|--------|-------------|
+| COLR/CPAL | COLR, CPAL | Layered vector glyphs |
+| sbix | sbix | Bitmap images (Apple) |
+| CBDT/CBLC | CBDT, CBLC | Bitmap images (Google) |
+| SVG | SVG | SVG embedded in font |
+
+## COLR/CPAL
+
+COLR/CPAL uses layered vector glyphs with palette-based coloring.
+
+### Advantages
+
+- **Scalable** — Vectors scale to any size
+- **Small file size** — Efficient compression
+- **Variable support** — Works with variable fonts
+- **Wide support** — Modern browsers and apps
+
+### Structure
+
+```
+COLR table:
+- Glyph layers (which glyphs make up each color glyph)
+- Layer order (back to front)
+
+CPAL table:
+- Color palettes (sets of colors)
+- Color values (RGBA for each palette entry)
+```
+
+## sbix
+
+sbix stores bitmap images at multiple resolutions (Apple format).
+
+### Advantages
+
+- **Photo-realistic** — Any image quality
+- **Multiple sizes** — Different bitmaps for different sizes
+
+### Structure
+
+```
+sbix table:
+- Strikes (image sets at different sizes)
+- Per-glyph images (PNG, JPG, etc.)
+```
+
+## CBDT/CBLC
+
+CBDT/CBLC stores bitmap images (Google/Android format).
+
+### Advantages
+
+- **Android support** — Primary Android bitmap format
+- **Multiple sizes** — Different bitmaps per ppem
+
+### Structure
+
+```
+CBLC table:
+- Location data (where each bitmap is)
+- Size information
+
+CBDT table:
+- Bitmap data (actual images)
+```
+
+## SVG Color Fonts
+
+SVG fonts embed complete SVG documents.
+
+### Advantages
+
+- **Full SVG features** — Gradients, effects, etc.
+- **Standalone** — No external resources
+
+### Limitations
+
+- **Large file size** — XML overhead
+- **Limited support** — Not all browsers
+
+## Guides
+
+- [COLR/CPAL](/guide/color-fonts/colr-cpal) — Vector layered color fonts
+- [Bitmaps](/guide/color-fonts/bitmaps) — sbix and CBDT/CBLC
+- [SVG Color](/guide/color-fonts/svg) — SVG-based color fonts
+
+## Quick Start
+
+### Check for Color Tables
+
+```ruby
+font = Fontisan::FontLoader.load('font.ttf')
+
+if font.tables['COLR']
+  puts "COLR/CPAL color font"
+end
+
+if font.tables['sbix']
+  puts "sbix bitmap font"
+end
+
+if font.tables['CBDT']
+  puts "CBDT/CBLC bitmap font"
+end
+
+if font.tables['SVG']
+  puts "SVG color font"
+end
+```
+
+### Get Color Information
+
+```ruby
+colr = font.tables['COLR']
+cpal = font.tables['CPAL']
+
+if colr && cpal
+  # Get base glyphs (color emoji)
+  colr.base_glyphs.each do |glyph_id|
+    puts "Base glyph: #{glyph_id}"
+    puts "  Layers: #{colr.layers_for(glyph_id).length}"
+
+    colr.layers_for(glyph_id).each do |layer|
+      color = cpal.color(layer[:palette_index])
+      puts "    Layer #{layer[:glyph_id]}: #{color}"
+    end
+  end
+end
+```

data/docs/guide/color-fonts/svg.md

@@ -0,0 +1,154 @@
+---
+title: SVG Color Fonts
+---
+
+# SVG Color Fonts
+
+SVG color fonts embed complete SVG documents for each glyph.
+
+## Overview
+
+SVG color fonts contain:
+- Full SVG documents with shapes, gradients, effects
+- Can be extremely detailed and complex
+- Self-contained (no external resources)
+
+## Structure
+
+```ruby
+svg = font.tables['SVG']
+
+# SVG documents by glyph ID
+svg.documents.each do |glyph_id, doc|
+  puts "Glyph #{glyph_id}:"
+  puts doc  # Complete SVG XML
+end
+```
+
+## Reading SVG Fonts
+
+### List SVG Glyphs
+
+```ruby
+font = Fontisan::FontLoader.load('svg-font.ttf')
+svg = font.tables['SVG']
+
+if svg
+  svg.documents.each do |glyph_id, doc|
+    glyph_name = font.glyph_name(glyph_id)
+    puts "#{glyph_name}: #{doc.length} bytes"
+  end
+end
+```
+
+### Parse SVG Content
+
+```ruby
+require 'nokogiri'
+
+svg = font.tables['SVG']
+doc = svg.documents[42]  # SVG for glyph 42
+
+parsed = Nokogiri::XML(doc)
+
+# Find elements
+paths = parsed.css('path')
+puts "Paths: #{paths.length}"
+
+rects = parsed.css('rect')
+puts "Rectangles: #{rects.length}"
+
+# Find gradients
+gradients = parsed.css('linearGradient', 'radialGradient')
+puts "Gradients: #{gradients.length}"
+```
+
+## SVG Features
+
+SVG fonts can include:
+
+| Feature | Support |
+|---------|---------|
+| Paths | ✓ |
+| Basic shapes | ✓ |
+| Gradients | ✓ |
+| Patterns | ✓ |
+| Clip paths | ✓ |
+| Masks | ✓ |
+| Filters | Limited |
+| Animations | No |
+| Scripts | No |
+
+## Exporting
+
+### Export SVG Files
+
+```ruby
+font = Fontisan::FontLoader.load('svg-font.ttf')
+svg = font.tables['SVG']
+
+Dir.mkdir('svg-glyphs') unless Dir.exist?('svg-glyphs')
+
+svg.documents.each do |glyph_id, doc|
+  glyph_name = font.glyph_name(glyph_id) || "glyph-#{glyph_id}"
+  filename = "svg-glyphs/#{glyph_name}.svg"
+  File.write(filename, doc)
+end
+```
+
+## Conversion
+
+### SVG to Other Formats
+
+```bash
+# SVG is preserved during conversion
+fontisan convert svg-font.ttf --to otf --output svg-font.otf
+```
+
+### Remove SVG
+
+```bash
+# Create version without SVG
+fontisan convert svg-font.ttf --to ttf --no-svg --output no-svg.ttf
+```
+
+## Limitations
+
+### File Size
+
+SVG fonts can be very large:
+- XML text overhead
+- Duplicate content across glyphs
+- Embedded gradients and filters
+
+### Browser Support
+
+| Browser | Support |
+|---------|---------|
+| Firefox | Full |
+| Safari | Full |
+| Chrome | Full (since v98) |
+| Edge | Full |
+
+### Performance
+
+- **Parsing** — SVG requires XML parsing
+- **Rendering** — Complex effects are slow
+- **Memory** — Large documents use more memory
+
+## Comparison with COLR/CPAL
+
+| Feature | SVG | COLR/CPAL |
+|---------|-----|-----------|
+| File size | Large | Small |
+| Effects | Full | Limited |
+| Gradients | Full | Limited |
+| Browser support | Good | Good |
+| Variable fonts | No | Yes |
+
+## Best Practices
+
+1. **Optimize SVGs** — Minimize file size
+2. **Use COLR/CPAL if possible** — Better performance
+3. **Test rendering** — Complex effects may not work everywhere
+4. **Provide fallbacks** — Not all platforms support SVG fonts

data/docs/guide/color.md

@@ -0,0 +1,51 @@
+# Color Fonts
+
+Fontisan supports working with color fonts in various formats.
+
+## Supported Formats
+
+- **COLR/CPAL** - OpenType color font tables
+- **SVG** - SVG-based color fonts
+- **CBDT/CBLC** - Color bitmap fonts
+
+## Reading Color Fonts
+
+```ruby
+require 'fontisan'
+
+# Load a color font
+font = Fontisan.load('color-font.ttf')
+
+# Check if font has color
+if font.color?
+  puts "This is a color font"
+  puts "Format: #{font.color_format}"
+end
+```
+
+## Color Palettes
+
+For COLR/CPAL fonts:
+
+```ruby
+# Get color palettes
+palettes = font.color_palettes
+
+palettes.each do |palette|
+  puts "Palette:"
+  palette.colors.each do |color|
+    puts "  ##{color.hex}"
+  end
+end
+```
+
+## Converting Color Fonts
+
+```ruby
+# Convert color font to WOFF2
+Fontisan.convert('color-font.ttf', output_format: :woff2)
+```
+
+## Related
+
+- [Variable Fonts](/guide/variable) - Variable font support

data/docs/guide/comparisons/font-validator.md

@@ -0,0 +1,222 @@
+---
+title: vs Font-Validator
+---
+
+# Fontisan vs Font-Validator
+
+Compare Fontisan with Microsoft's Font-Validator.
+
+## Overview
+
+Font-Validator is Microsoft's C# tool for comprehensive font validation.
+
+| | Font-Validator | Fontisan |
+|---|----------------|----------|
+| Language | C# | Ruby |
+| Runtime | .NET required | None |
+| Platform | Windows focus | Cross-platform |
+| Features | Validation only | Full suite |
+
+## Profile Equivalents
+
+| Font-Validator | Fontisan |
+|----------------|----------|
+| Auto | `fontisan validate -t indexability` |
+| Full | `fontisan validate -t production` |
+| Web | `fontisan validate -t web` |
+| Custom | `fontisan validate -t spec_compliance` |
+
+## Feature Comparison
+
+### Validation
+
+| Feature | Font-Validator | Fontisan |
+|---------|----------------|----------|
+| Profiles | 3+ | 5 |
+| Helpers | ~50 | 56 |
+| Coverage reports | ✅ | ✅ |
+| Custom rules | ❌ | ✅ |
+| Severity levels | ✅ | ✅ |
+| Output formats | XML | YAML, JSON, Text |
+
+### Font Operations
+
+| Feature | Font-Validator | Fontisan |
+|---------|----------------|----------|
+| Validation | ✅ | ✅ |
+| Conversion | ❌ | ✅ |
+| Subsetting | ❌ | ✅ |
+| Information | Limited | ✅ |
+| Collections | Limited | ✅ |
+
+### Format Support
+
+| Format | Font-Validator | Fontisan |
+|--------|----------------|----------|
+| TrueType | ✅ | ✅ |
+| OpenType | ✅ | ✅ |
+| WOFF | ✅ | ✅ |
+| WOFF2 | ✅ | ✅ |
+| Type 1 | ❌ | ✅ |
+| TTC/OTC | Limited | ✅ |
+
+### Variable Fonts
+
+| Feature | Font-Validator | Fontisan |
+|---------|----------------|----------|
+| fvar validation | ✅ | ✅ |
+| gvar validation | ✅ | ✅ |
+| Instance generation | ❌ | ✅ |
+| Format conversion | ❌ | ✅ |
+
+## Validation Profiles
+
+### Fontisan Profiles
+
+| Profile | Checks | Focus |
+|---------|--------|-------|
+| indexability | 8 | Fast discovery |
+| usability | 26 | Installation |
+| production | 37 | Full quality |
+| web | 18 | Web fonts |
+| spec_compliance | Full | Spec audit |
+
+### Font-Validator Profiles
+
+| Profile | Focus |
+|---------|-------|
+| Auto | Quick check |
+| Full | Comprehensive |
+| Web | Web fonts |
+
+## Unique Features
+
+### Fontisan Unique
+
+- **Pure Ruby** — No .NET runtime
+- **Font conversion** — TTF ↔ OTF ↔ WOFF
+- **Subsetting** — Create font subsets
+- **Collections** — Full TTC/OTC support
+- **Custom validators** — DSL for rules
+- **Variable fonts** — Instance generation
+- **Type 1 support** — Legacy format
+
+### Font-Validator Unique
+
+- **Microsoft official** — From the source
+- **Deep Windows integration** — Windows-specific checks
+- **Mature** — Long development history
+
+## Installation Comparison
+
+### Font-Validator
+
+```bash
+# Requires .NET runtime
+# Windows: Download MSI
+# Linux: Requires Mono or .NET Core
+# macOS: Requires .NET Core
+
+dotnet tool install --global FontValidator
+```
+
+### Fontisan
+
+```bash
+# All platforms, no runtime
+gem install fontisan
+```
+
+## Use Case Recommendations
+
+### Use Fontisan When:
+
+- You're not on Windows
+- You need conversion features
+- You need subsetting
+- You want custom validators
+- You need Type 1 support
+
+### Use Font-Validator When:
+
+- You need Microsoft official validation
+- You need Windows-specific checks
+- You're in a .NET environment
+
+## Code Comparison
+
+### Basic Validation
+
+```bash
+# Font-Validator
+FontValidator.exe font.ttf
+
+# Fontisan
+fontisan validate font.ttf
+```
+
+### With Profile
+
+```bash
+# Font-Validator
+FontValidator.exe -Profile Full font.ttf
+
+# Fontisan
+fontisan validate font.ttf -t production
+```
+
+### Output Format
+
+```bash
+# Font-Validator
+FontValidator.exe -Output report.xml font.ttf
+
+# Fontisan
+fontisan validate font.ttf --format json
+```
+
+## Custom Validators
+
+Fontisan allows custom validation rules (not available in Font-Validator):
+
+```ruby
+class MyValidator < Fontisan::Validators::Validator
+  def define_checks
+    check_table :name_check, 'name', severity: :error do |table|
+      table.family_name_present? &&
+        table.postscript_name_valid?
+    end
+  end
+end
+```
+
+## CI/CD Integration
+
+### Font-Validator
+
+```yaml
+# Requires .NET runtime
+- uses: actions/setup-dotnet@v3
+- run: FontValidator.exe fonts/*.ttf
+```
+
+### Fontisan
+
+```yaml
+# Uses Ruby (already available on most runners)
+- uses: ruby/setup-ruby@v1
+- run: gem install fontisan
+- run: fontisan validate fonts/*.ttf
+```
+
+## Conclusion
+
+| Need | Recommendation |
+|------|----------------|
+| Ruby environment | Fontisan |
+| Cross-platform | Fontisan |
+| Conversion features | Fontisan |
+| Custom validation | Fontisan |
+| Microsoft official | Font-Validator |
+| Windows-specific | Font-Validator |
+| .NET environment | Font-Validator |