fontisan 0.2.13 → 0.2.16

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

@@ -0,0 +1,260 @@
+---
+title: Migrate from Font-Validator
+---
+
+# Migrate from Font-Validator
+
+This guide helps you migrate from Microsoft's Font-Validator (C#) to Fontisan.
+
+## Overview
+
+Font-Validator is Microsoft's C# tool for font validation. Fontisan provides equivalent validation with additional features, all in pure Ruby.
+
+## Profile Equivalents
+
+| Font-Validator | Fontisan |
+|----------------|----------|
+| Auto mode | `fontisan validate -t indexability` |
+| Full mode | `fontisan validate -t production` |
+| Web mode | `fontisan validate -t web` |
+| Custom | `fontisan validate -t spec_compliance` |
+
+## Validation Profiles
+
+### indexability (Fast)
+
+Equivalent to Font-Validator Auto mode:
+
+```bash
+fontisan validate font.ttf -t indexability
+
+# Fast validation for font discovery
+# 8 checks, metadata-only
+```
+
+### production (Full)
+
+Equivalent to Font-Validator Full mode:
+
+```bash
+fontisan validate font.ttf -t production
+
+# Comprehensive quality checks
+# 37 checks, OpenType spec compliance
+# This is the default profile
+```
+
+### web
+
+Equivalent to Font-Validator Web mode:
+
+```bash
+fontisan validate font.ttf -t web
+
+# Web embedding readiness
+# 18 checks for web deployment
+```
+
+## Command Equivalents
+
+### Basic Validation
+
+**Font-Validator:**
+```bash
+FontValidator.exe font.ttf
+```
+
+**Fontisan:**
+```bash
+fontisan validate font.ttf
+```
+
+### With Profile
+
+**Font-Validator:**
+```bash
+FontValidator.exe -Profile Auto font.ttf
+FontValidator.exe -Profile Full font.ttf
+FontValidator.exe -Profile Web font.ttf
+```
+
+**Fontisan:**
+```bash
+fontisan validate font.ttf -t indexability
+fontisan validate font.ttf -t production
+fontisan validate font.ttf -t web
+```
+
+### Output Format
+
+**Font-Validator:**
+```bash
+FontValidator.exe -Output report.xml font.ttf
+```
+
+**Fontisan:**
+```bash
+fontisan validate font.ttf --format yaml
+fontisan validate font.ttf --format json
+```
+
+## Output Comparison
+
+### Font-Validator Output
+
+```
+=== Font Validation Report ===
+File: font.ttf
+Overall: PASS
+
+Checks: 50
+Passed: 50
+Failed: 0
+```
+
+### Fontisan Output
+
+```
+Font: font.ttf
+Status: VALID
+
+Summary:
+  Checks performed: 37
+  Passed: 37
+  Failed: 0
+
+Errors: 0
+Warnings: 0
+```
+
+## Validation Helpers
+
+Fontisan includes 56 validation helpers:
+
+| Category | Helpers |
+|----------|---------|
+| Table | 12 |
+| Name | 8 |
+| Head | 6 |
+| Metrics | 10 |
+| Glyph | 8 |
+| CMAP | 6 |
+| Layout | 6 |
+
+See [Validation Helpers](/guide/validation/helpers) for details.
+
+## Additional Features
+
+Fontisan provides features not available in Font-Validator:
+
+### Font Conversion
+
+```bash
+# Not available in Font-Validator
+fontisan convert font.ttf --to otf --output font.otf
+fontisan convert font.ttf --to woff2 --output font.woff2
+```
+
+### Font Subsetting
+
+```bash
+# Not available in Font-Validator
+fontisan subset font.ttf --chars "ABC" --output subset.ttf
+```
+
+### Collection Support
+
+```bash
+# Limited in Font-Validator
+fontisan ls family.ttc
+fontisan unpack family.ttc --output-dir ./extracted
+```
+
+### Variable Font Support
+
+```bash
+# Limited in Font-Validator
+fontisan info variable.ttf
+fontisan instance variable.ttf --wght 700 --output bold.ttf
+```
+
+## Feature Comparison
+
+| Feature | Font-Validator | Fontisan |
+|---------|----------------|----------|
+| Pure Ruby | ❌ (C#) | ✅ |
+| .NET required | ✅ | ❌ |
+| Validation | ✅ | ✅ |
+| Conversion | ❌ | ✅ |
+| Subsetting | ❌ | ✅ |
+| Collections | Limited | ✅ |
+| Variable fonts | Limited | ✅ |
+| Type 1 support | ❌ | ✅ |
+| Custom validators | ❌ | ✅ |
+
+## Migration Example
+
+### CI/CD Pipeline
+
+**Before (Font-Validator):**
+```yaml
+# Requires .NET runtime
+- run: FontValidator.exe -Profile Full fonts/*.ttf
+```
+
+**After (Fontisan):**
+```yaml
+# Pure Ruby, no runtime dependencies
+- run: fontisan validate fonts/*.ttf -t production
+```
+
+### Script
+
+**Before:**
+```bash
+# Windows only
+FontValidator.exe -Profile Full font.ttf
+if %ERRORLEVEL% neq 0 (
+  echo Validation failed
+)
+```
+
+**After:**
+```bash
+# Cross-platform
+fontisan validate font.ttf
+if [ $? -ne 0 ]; then
+  echo "Validation failed"
+fi
+```
+
+## Custom Validators
+
+Fontisan allows custom validation rules:
+
+```ruby
+class MyValidator < Fontisan::Validators::Validator
+  def define_checks
+    check_table :custom_check, 'name', severity: :error do |table|
+      table.family_name_present?
+    end
+  end
+end
+```
+
+See [Custom Validators](/guide/validation/custom) for details.
+
+## Advantages of Fontisan
+
+1. **Pure Ruby** — No .NET runtime required
+2. **Cross-platform** — Works on Linux, macOS, Windows
+3. **More features** — Conversion, subsetting, collections
+4. **Custom validators** — Extensible validation
+5. **Variable fonts** — Full support
+6. **Type 1** — Legacy format support
+
+## Getting Help
+
+- [Validation Guide](/guide/validation/)
+- [CLI Reference](/guide/cli/validate)
+- [GitHub Issues](https://github.com/fontist/fontisan/issues)

data/docs/guide/migrations/fonttools.md

@@ -0,0 +1,208 @@
+---
+title: Migrate from fonttools
+---
+
+# Migrate from fonttools (Python)
+
+This guide helps you migrate from Python's fonttools library to Fontisan.
+
+## Overview
+
+| fonttools (Python) | Fontisan (Ruby) |
+|--------------------|-----------------|
+| Python required | Pure Ruby |
+| Native extensions | Pure Ruby |
+| No validation | Built-in validation |
+| Partial Type 1 | Full Type 1 support |
+
+## Quick Reference
+
+### Loading Fonts
+
+```python
+# fonttools
+from fontTools.ttLib import TTFont
+font = TTFont('font.ttf')
+```
+
+```ruby
+# Fontisan
+font = Fontisan::FontLoader.load('font.ttf')
+```
+
+### Saving Fonts
+
+```python
+# fonttools
+font.save('output.ttf')
+```
+
+```ruby
+# Fontisan
+Fontisan::FontWriter.write(font, 'output.ttf')
+```
+
+### TTX Export
+
+```bash
+# fonttools
+ttx font.ttf
+
+# Fontisan
+fontisan export font.ttf --format ttx --output font.ttx
+```
+
+## Command Equivalents
+
+### ttx
+
+| fonttools | Fontisan |
+|-----------|----------|
+| `ttx font.ttf` | `fontisan export font.ttf --format ttx` |
+| `ttx -t name font.ttf` | `fontisan export font.ttf --format ttx --tables name` |
+| `ttx -o output.ttx font.ttf` | `fontisan export font.ttf --format ttx --output output.ttx` |
+
+### fonttools subset
+
+| fonttools | Fontisan |
+|-----------|----------|
+| `fonttools subset font.ttf --text="ABC"` | `fontisan subset font.ttf --chars "ABC"` |
+| `fonttools subset font.ttf --unicodes="U+0041"` | `fontisan subset font.ttf --unicodes "U+0041"` |
+| `fonttools subset font.ttf --output-file=out.ttf` | `fontisan subset font.ttf --output out.ttf` |
+
+## API Migration
+
+### Access Tables
+
+```python
+# fonttools
+name_table = font['name']
+family = name_table.getBestFamilyName()
+```
+
+```ruby
+# Fontisan
+name_table = font.tables['name']
+family = name_table.family_name
+```
+
+### Get Glyph Count
+
+```python
+# fonttools
+num_glyphs = font['maxp'].numGlyphs
+```
+
+```ruby
+# Fontisan
+num_glyphs = font.tables['maxp'].num_glyphs
+```
+
+### Iterate Glyphs
+
+```python
+# fonttools
+for glyph_name in font.getGlyphOrder():
+    print(glyph_name)
+```
+
+```ruby
+# Fontisan
+font.glyphs.each_with_index do |glyph, id|
+  puts font.glyph_name(id)
+end
+```
+
+### Variable Fonts
+
+```python
+# fonttools
+axes = font['fvar'].axes
+for axis in axes:
+    print(axis.axisTag, axis.minValue, axis.maxValue)
+```
+
+```ruby
+# Fontisan
+fvar = font.tables['fvar']
+fvar.axes.each do |axis|
+  puts "#{axis.tag}: #{axis.min_value} - #{axis.max_value}"
+end
+```
+
+### Generate Instance
+
+```python
+# fonttools
+from fontTools.varLib.instancer import instantiateVariableFont
+instance = instantiateVariableFont(font, {'wght': 700})
+```
+
+```ruby
+# Fontisan
+writer = Fontisan::Variation::InstanceWriter.new(font)
+instance = writer.generate_instance(wght: 700)
+```
+
+## Feature Comparison
+
+| Feature | fonttools | Fontisan |
+|---------|-----------|----------|
+| Pure Ruby | ❌ | ✅ |
+| Python-free | ❌ | ✅ |
+| TTF/OTF support | ✅ | ✅ |
+| WOFF/WOFF2 | ✅ | ✅ |
+| Type 1 support | Partial | ✅ |
+| Variable fonts | ✅ | ✅ |
+| Font validation | ❌ | ✅ |
+| Hint conversion | ❌ | ✅ |
+| Collections | ✅ | ✅ |
+| UFO format | ✅ | Planned |
+| FEA parsing | ✅ | ❌ |
+| Designspace | ✅ | ❌ |
+
+## Advantages of Fontisan
+
+### Pure Ruby
+
+- No Python installation required
+- No native extension compilation
+- Works in Ruby-only environments
+- Easy deployment
+
+### Built-in Validation
+
+```ruby
+# Fontisan has validation built-in
+result = Fontisan.validate('font.ttf', profile: :production)
+puts result.valid?
+```
+
+### Bidirectional Hint Conversion
+
+```ruby
+# Convert hints between TrueType and PostScript
+fontisan convert font.ttf --to otf --hinting-mode preserve
+```
+
+### Type 1 Support
+
+```ruby
+# Full Type 1 support including conversion
+fontisan convert font.pfb --to otf --output font.otf
+```
+
+## Migration Checklist
+
+1. [ ] Install Fontisan: `gem install fontisan`
+2. [ ] Replace `from fontTools.ttLib import TTFont` with `require 'fontisan'`
+3. [ ] Replace `TTFont(path)` with `Fontisan::FontLoader.load(path)`
+4. [ ] Replace `font.save(path)` with `Fontisan::FontWriter.write(font, path)`
+5. [ ] Update table access from `font['name']` to `font.tables['name']`
+6. [ ] Test your workflow
+
+## Getting Help
+
+- [Fontisan Guide](/guide/)
+- [API Reference](/api/)
+- [GitHub Issues](https://github.com/fontist/fontisan/issues)

data/docs/guide/migrations/index.md

@@ -0,0 +1,64 @@
+---
+title: Migration Guides
+---
+
+# Migration Guides
+
+Migrating from another font tool? These guides will help you transition to Fontisan.
+
+## Available Guides
+
+### From fonttools (Python)
+
+[→ Migrate from fonttools](/guide/migrations/fonttools)
+
+The most comprehensive migration guide covering:
+- API equivalents for `TTFont`, `fontTools.varLib`, etc.
+- CLI command mapping
+- Feature comparison table
+- Common workflows
+
+### From extract_ttc
+
+[→ Migrate from extract_ttc](/guide/migrations/extract-ttc)
+
+Fontisan fully supersedes extract_ttc:
+- Identical `ls` and `info` commands
+- More powerful `unpack` with format conversion
+- Works on TTF/OTF files too
+- Table sharing statistics
+
+### From otfinfo (lcdf-typetools)
+
+[→ Migrate from otfinfo](/guide/migrations/otfinfo)
+
+Command equivalents for lcdf-typetools users:
+- `otfinfo -i` → `fontisan info`
+- `otfinfo -s` → `fontisan scripts`
+- `otfinfo -f` → `fontisan features`
+- `otfinfo -g` → `fontisan glyphs`
+
+### From Font-Validator
+
+[→ Migrate from Font-Validator](/guide/migrations/font-validator)
+
+Validation profile mapping:
+- Auto mode → `fontisan validate -t indexability`
+- Full mode → `fontisan validate -t production`
+- Web mode → `fontisan validate -t web`
+
+## Why Migrate?
+
+| Feature | fonttools | lcdf-typetools | Font-Validator | Fontisan |
+|---------|-----------|----------------|----------------|----------|
+| Pure Ruby | ❌ | ❌ | ❌ | ✅ |
+| Font conversion | ✅ | ✅ | ❌ | ✅ |
+| Validation | ❌ | ❌ | ✅ | ✅ |
+| Variable fonts | ✅ | ❌ | ❌ | ✅ |
+| Type 1 support | Partial | ✅ | ❌ | ✅ |
+| Bidirectional hints | ❌ | Partial | ❌ | ✅ |
+
+## Need Help?
+
+- [GitHub Issues](https://github.com/fontist/fontisan/issues) — Report bugs or request features
+- [Guide](/guide/) — Read the documentation

data/docs/guide/migrations/otfinfo.md

@@ -0,0 +1,197 @@
+---
+title: Migrate from otfinfo
+---
+
+# Migrate from otfinfo
+
+This guide helps you migrate from otfinfo (lcdf-typetools) to Fontisan.
+
+## Overview
+
+otfinfo is part of the lcdf-typetools suite. Fontisan provides equivalent functionality with additional features.
+
+## Command Equivalents
+
+### Font Information
+
+| otfinfo | Fontisan |
+|---------|----------|
+| `otfinfo -i font.ttf` | `fontisan info font.ttf` |
+| `otfinfo --info font.ttf` | `fontisan info font.ttf` |
+
+### Script Information
+
+| otfinfo | Fontisan |
+|---------|----------|
+| `otfinfo -s font.ttf` | `fontisan info font.ttf --features` |
+| `otfinfo --scripts font.ttf` | `fontisan info font.ttf --features` |
+
+### Feature Information
+
+| otfinfo | Fontisan |
+|---------|----------|
+| `otfinfo -f font.ttf` | `fontisan info font.ttf --features` |
+| `otfinfo --features font.ttf` | `fontisan info font.ttf --features` |
+
+### Glyph Information
+
+| otfinfo | Fontisan |
+|---------|----------|
+| `otfinfo -g font.ttf` | `fontisan info font.ttf --glyphs` |
+| `otfinfo --glyphs font.ttf` | `fontisan info font.ttf --glyphs` |
+
+### Unicode Coverage
+
+| otfinfo | Fontisan |
+|---------|----------|
+| `otfinfo -u font.ttf` | `fontisan info font.ttf --unicode` |
+| `otfinfo --unicode font.ttf` | `fontisan info font.ttf --unicode` |
+
+### Table Information
+
+| otfinfo | Fontisan |
+|---------|----------|
+| `otfinfo -t font.ttf` | `fontisan info font.ttf --tables` |
+| `otfinfo --tables font.ttf` | `fontisan info font.ttf --tables` |
+
+## Output Comparison
+
+### Font Information
+
+**otfinfo:**
+```
+Family:              Example
+Subfamily:           Regular
+Full name:           Example Regular
+PostScript name:     Example-Regular
+Version:             1.000
+```
+
+**Fontisan:**
+```
+Font: font.ttf
+Format: TrueType
+Family: Example
+Style: Regular
+PostScript: Example-Regular
+Version: 1.000
+Glyphs: 268
+Tables: 14
+```
+
+### Unicode Coverage
+
+**otfinfo:**
+```
+U+0020..U+007E Basic Latin
+U+00A0..U+00FF Latin-1 Supplement
+```
+
+**Fontisan:**
+```
+Unicode Coverage:
+  Basic Latin (U+0020-U+007E)
+  Latin-1 Supplement (U+00A0-U+00FF)
+```
+
+## Additional Features
+
+Fontisan provides features not available in otfinfo:
+
+### Validation
+
+```bash
+# Not available in otfinfo
+fontisan validate font.ttf --profile production
+```
+
+### Conversion
+
+```bash
+# Not available in otfinfo
+fontisan convert font.ttf --to otf --output font.otf
+```
+
+### Subsetting
+
+```bash
+# Not available in otfinfo
+fontisan subset font.ttf --chars "ABC" --output subset.ttf
+```
+
+### Collection Support
+
+```bash
+# Limited in otfinfo
+fontisan ls family.ttc
+fontisan unpack family.ttc --output-dir ./extracted
+```
+
+### Multiple Output Formats
+
+```bash
+# otfinfo: text only
+# Fontisan: text, YAML, JSON
+
+fontisan info font.ttf --format yaml
+fontisan info font.ttf --format json
+```
+
+## Feature Comparison
+
+| Feature | otfinfo | Fontisan |
+|---------|---------|----------|
+| Font info | ✅ | ✅ |
+| Script info | ✅ | ✅ |
+| Feature info | ✅ | ✅ |
+| Glyph info | ✅ | ✅ |
+| Unicode info | ✅ | ✅ |
+| Table info | ✅ | ✅ |
+| Validation | ❌ | ✅ |
+| Conversion | ❌ | ✅ |
+| Subsetting | ❌ | ✅ |
+| Collections | Limited | ✅ |
+| YAML/JSON | ❌ | ✅ |
+| Pure Ruby | ❌ (C++) | ✅ |
+
+## Migration Example
+
+### Before (otfinfo)
+
+```bash
+# Get family name
+family=$(otfinfo -i font.ttf | grep Family | cut -d: -f2 | xargs)
+echo "Family: $family"
+
+# Check for specific feature
+if otfinfo -f font.ttf | grep -q "liga"; then
+  echo "Has ligatures"
+fi
+```
+
+### After (Fontisan)
+
+```bash
+# Get family name (JSON output)
+family=$(fontisan info font.ttf --format json | jq -r '.family')
+echo "Family: $family"
+
+# Check for specific feature
+if fontisan info font.ttf --features | grep -q "liga"; then
+  echo "Has ligatures"
+fi
+```
+
+## Advantages of Fontisan
+
+1. **Pure Ruby** — No C++ compilation required
+2. **More features** — Validation, conversion, subsetting
+3. **Better output** — YAML and JSON formats
+4. **Collection support** — Full TTC/OTC handling
+5. **Validation** — Comprehensive font checking
+
+## Getting Help
+
+- [Fontisan Guide](/guide/)
+- [CLI Reference](/guide/cli/)
+- [GitHub Issues](https://github.com/fontist/fontisan/issues)