fontisan 0.2.14 → 0.2.17

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 |

data/docs/guide/comparisons/fonttools.md

@@ -0,0 +1,200 @@
+---
+title: vs fonttools
+---
+
+# Fontisan vs fonttools
+
+Compare Fontisan with Python's fonttools library.
+
+## Overview
+
+| | fonttools | Fontisan |
+|---|-----------|----------|
+| Language | Python | Ruby |
+| Dependencies | Python + extensions | Pure Ruby |
+| Native code | Required | None |
+| Validation | External tools | Built-in |
+
+## Feature Comparison
+
+### Font Formats
+
+| Format | fonttools | Fontisan |
+|--------|-----------|----------|
+| TrueType (TTF) | ✅ | ✅ |
+| OpenType (OTF) | ✅ | ✅ |
+| WOFF | ✅ | ✅ |
+| WOFF2 | ✅ | ✅ |
+| Type 1 (PFB/PFA) | Partial | ✅ |
+| TTC/OTC | ✅ | ✅ |
+| dfont | ✅ | ✅ |
+| SVG | ✅ | ✅ |
+| UFO | ✅ | Planned |
+
+### Font Operations
+
+| Operation | fonttools | Fontisan |
+|-----------|-----------|----------|
+| Font loading | ✅ | ✅ |
+| Font saving | ✅ | ✅ |
+| Table access | ✅ | ✅ |
+| TTX export | ✅ | ✅ |
+| Subsetting | ✅ | ✅ |
+| Merging | ✅ | ✅ |
+
+### Variable Fonts
+
+| Feature | fonttools | Fontisan |
+|---------|-----------|----------|
+| fvar reading | ✅ | ✅ |
+| gvar reading | ✅ | ✅ |
+| CFF2 reading | ✅ | ✅ |
+| Instance generation | ✅ | ✅ |
+| Format conversion | ✅ | ✅ |
+
+### Font Conversion
+
+| Conversion | fonttools | Fontisan |
+|------------|-----------|----------|
+| TTF ↔ OTF | ✅ | ✅ |
+| TTF ↔ WOFF | ✅ | ✅ |
+| TTF ↔ WOFF2 | ✅ | ✅ |
+| Type 1 → OTF | ✅ | ✅ |
+| OTF → Type 1 | ❌ | ✅ |
+| Curve conversion | ✅ | ✅ |
+
+### Hinting
+
+| Feature | fonttools | Fontisan |
+|---------|-----------|----------|
+| TrueType instructions | Read | Read |
+| PostScript hints | Read | Read |
+| Hint conversion | ❌ | ✅ |
+| Bidirectional | ❌ | ✅ |
+| Autohint | External | ✅ |
+
+### Validation
+
+| Feature | fonttools | Fontisan |
+|---------|-----------|----------|
+| Built-in validation | ❌ | ✅ |
+| Validation profiles | ❌ | ✅ (5) |
+| Validation helpers | ❌ | ✅ (56) |
+| Custom validators | ❌ | ✅ |
+| Coverage reports | ❌ | ✅ |
+
+### Collections
+
+| Feature | fonttools | Fontisan |
+|---------|-----------|----------|
+| TTC/OTC reading | ✅ | ✅ |
+| TTC/OTC writing | ✅ | ✅ |
+| Table deduplication | ✅ | ✅ |
+| dfont support | ✅ | ✅ |
+
+## Unique Features
+
+### Fontisan Unique
+
+- **Pure Ruby** — No Python, no native extensions
+- **Built-in validation** — 5 profiles, 56 helpers
+- **Bidirectional hint conversion** — TrueType ↔ PostScript
+- **Custom validators** — DSL for validation rules
+- **Type 1 roundtrip** — Full conversion support
+
+### fonttools Unique
+
+- **UFO format** — Full UFO 3 support
+- **FEA parsing** — Adobe Feature Expressions
+- **Designspace** — MutatorMath integration
+- **Extensive ecosystem** — Many third-party tools
+
+## Performance
+
+### Installation
+
+| Metric | fonttools | Fontisan |
+|--------|-----------|----------|
+| Python required | Yes | No |
+| C extensions | Often required | No |
+| Install time | 30-60s | 5-10s |
+| Dependencies | Many | None |
+
+### Runtime
+
+Both libraries are fast enough for most use cases. Fontisan's pure Ruby approach has minimal overhead for typical operations.
+
+## Use Case Recommendations
+
+### Use Fontisan When:
+
+- You're in a Ruby environment
+- You need validation built-in
+- You need hint conversion
+- You want minimal dependencies
+- You're deploying to constrained environments
+
+### Use fonttools When:
+
+- You're in a Python environment
+- You need UFO/FEA support
+- You need Designspace support
+- You rely on the Python font ecosystem
+
+## Code Comparison
+
+### Load and Save
+
+```python
+# fonttools
+from fontTools.ttLib import TTFont
+font = TTFont('input.ttf')
+font.save('output.ttf')
+```
+
+```ruby
+# Fontisan
+font = Fontisan::FontLoader.load('input.ttf')
+Fontisan::FontWriter.write(font, 'output.ttf')
+```
+
+### Access Table
+
+```python
+# fonttools
+name = font['name'].getBestFamilyName()
+```
+
+```ruby
+# Fontisan
+name = font.tables['name'].family_name
+```
+
+### Variable Font 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)
+```
+
+## Migration
+
+See [Migrate from fonttools](/guide/migrations/fonttools) for a detailed migration guide.
+
+## Conclusion
+
+| Need | Recommendation |
+|------|----------------|
+| Ruby environment | Fontisan |
+| Python environment | fonttools |
+| Validation | Fontisan |
+| UFO/FEA | fonttools |
+| Hint conversion | Fontisan |
+| Minimal dependencies | Fontisan |

data/docs/guide/comparisons/index.md

@@ -0,0 +1,83 @@
+---
+title: Feature Comparisons
+---
+
+# Feature Comparisons
+
+Compare Fontisan's capabilities with other popular font processing tools.
+
+## Comparison Pages
+
+### vs fonttools
+
+[→ Compare with fonttools](/guide/comparisons/fonttools)
+
+Comprehensive comparison with Python's fonttools library:
+- Font formats (TTF, OTF, TTC, WOFF, WOFF2, Type 1, SVG, UFO)
+- Variable fonts (instancing, conversion, axes)
+- Font conversion (TTF↔OTF, curves, hints)
+- Font validation
+- Color fonts
+- Hinting
+- Collections
+
+### vs lcdf-typetools
+
+[→ Compare with lcdf-typetools](/guide/comparisons/lcdf-typetools)
+
+Comparison with the lcdf-typetools suite (otfinfo, cfftot1, etc.):
+- Font information extraction
+- CFF/Type 1 conversion
+- Font validation
+- Hint handling
+
+### vs Font-Validator
+
+[→ Compare with Font-Validator](/guide/comparisons/font-validator)
+
+Comparison with Microsoft's Font-Validator:
+- Validation profiles
+- Helper coverage
+- Reporting capabilities
+
+## Key Advantages
+
+### 💎 Pure Ruby
+
+Fontisan is 100% pure Ruby with no external dependencies:
+
+- **No Python** required (unlike fonttools)
+- **No C++ compilation** needed (unlike lcdf-typetools)
+- **No .NET runtime** required (unlike Font-Validator)
+- Works anywhere Ruby runs — Linux, macOS, Windows, BSD
+
+### 🔄 Bidirectional Hint Conversion
+
+Fontisan is the **only** library that supports bidirectional hint conversion:
+
+- TrueType instructions → PostScript hints
+- PostScript hints → TrueType instructions
+- Automatic hint generation (autohint)
+
+### ✅ Built-in Validation
+
+Unlike fonttools, Fontisan includes comprehensive validation:
+
+- 5 validation profiles
+- 56 validation helpers
+- Custom validation DSL
+- Detailed error reporting
+
+### 📦 All-in-One
+
+Fontisan combines capabilities from multiple tools:
+
+| Capability | fonttools | lcdf-typetools | Font-Validator | Fontisan |
+|-----------|-----------|----------------|----------------|----------|
+| Font conversion | ✅ | ✅ | ❌ | ✅ |
+| Font validation | ❌ | ❌ | ✅ | ✅ |
+| Variable fonts | ✅ | ❌ | ❌ | ✅ |
+| Type 1 support | Partial | ✅ | ❌ | ✅ |
+| Color fonts | ✅ | ❌ | ❌ | ✅ |
+| Hint conversion | ❌ | Partial | ❌ | ✅ |
+| **Pure Ruby** | ❌ | ❌ | ❌ | ✅ |

data/docs/guide/comparisons/lcdf-typetools.md

@@ -0,0 +1,205 @@
+---
+title: vs lcdf-typetools
+---
+
+# Fontisan vs lcdf-typetools
+
+Compare Fontisan with the lcdf-typetools suite (otfinfo, cfftot1, t1dotlessj, etc.).
+
+## Overview
+
+lcdf-typetools is a C++ suite including:
+- `otfinfo` — Font information
+- `cfftot1` — CFF to Type 1 conversion
+- `t1dotlessj` — Type 1 manipulation
+- `t1reencode` — Type 1 reencoding
+- `ttf2otf` — TTF to OTF conversion
+
+| | lcdf-typetools | Fontisan |
+|---|----------------|----------|
+| Language | C++ | Ruby |
+| Compilation | Required | None |
+| Installation | Complex | `gem install` |
+| Cross-platform | Limited | Full |
+
+## Tool Equivalents
+
+### otfinfo
+
+| otfinfo | Fontisan |
+|---------|----------|
+| `otfinfo -i font.ttf` | `fontisan info font.ttf` |
+| `otfinfo -s font.ttf` | `fontisan info font.ttf --features` |
+| `otfinfo -f font.ttf` | `fontisan info font.ttf --features` |
+| `otfinfo -g font.ttf` | `fontisan info font.ttf --glyphs` |
+| `otfinfo -u font.ttf` | `fontisan info font.ttf --unicode` |
+| `otfinfo -t font.ttf` | `fontisan info font.ttf --tables` |
+
+### cfftot1
+
+| cfftot1 | Fontisan |
+|---------|----------|
+| `cfftot1 font.otf` | `fontisan convert font.otf --to type1 --output font.pfb` |
+
+### t1reencode
+
+| t1reencode | Fontisan |
+|------------|----------|
+| `t1reencode font.pfb` | `fontisan convert font.pfb --to type1 --auto-encoding` |
+
+### ttf2otf
+
+| ttf2otf | Fontisan |
+|---------|----------|
+| `ttf2otf font.ttf` | `fontisan convert font.ttf --to otf --output font.otf` |
+
+## Feature Comparison
+
+### Font Information
+
+| Feature | otfinfo | Fontisan |
+|---------|---------|----------|
+| Basic info | ✅ | ✅ |
+| Script info | ✅ | ✅ |
+| Feature info | ✅ | ✅ |
+| Glyph info | ✅ | ✅ |
+| Unicode info | ✅ | ✅ |
+| Table info | ✅ | ✅ |
+| YAML/JSON | ❌ | ✅ |
+
+### Font Conversion
+
+| Feature | lcdf-typetools | Fontisan |
+|---------|----------------|----------|
+| TTF → OTF | ✅ (ttf2otf) | ✅ |
+| OTF → TTF | ❌ | ✅ |
+| OTF → Type 1 | ✅ (cfftot1) | ✅ |
+| Type 1 → OTF | ❌ | ✅ |
+| TTF → WOFF2 | ❌ | ✅ |
+
+### Hinting
+
+| Feature | lcdf-typetools | Fontisan |
+|---------|----------------|----------|
+| TrueType hints | Read | Read |
+| PostScript hints | Read | Read |
+| Hint conversion | Partial | ✅ |
+| Bidirectional | ❌ | ✅ |
+
+### Validation
+
+| Feature | lcdf-typetools | Fontisan |
+|---------|----------------|----------|
+| Validation | ❌ | ✅ |
+| Profiles | ❌ | ✅ (5) |
+| Helpers | ❌ | ✅ (56) |
+
+### Collections
+
+| Feature | lcdf-typetools | Fontisan |
+|---------|----------------|----------|
+| TTC/OTC reading | ❌ | ✅ |
+| TTC/OTC writing | ❌ | ✅ |
+| dfont support | ❌ | ✅ |
+
+## Unique Features
+
+### Fontisan Unique
+
+- **Pure Ruby** — No C++ compilation
+- **Built-in validation** — Comprehensive checking
+- **Bidirectional hint conversion** — TrueType ↔ PostScript
+- **Full collection support** — TTC/OTC/dfont
+- **Type 1 → OTF** — Reverse conversion
+- **WOFF/WOFF2** — Web font support
+
+### lcdf-typetools Unique
+
+- **t1dotlessj** — Specialized Type 1 manipulation
+- **t1lint** — Type 1 linting
+- **Fast C++** — Native performance
+- **Mature** — Long history
+
+## Installation Comparison
+
+### lcdf-typetools
+
+```bash
+# macOS
+brew install lcdf-typetools
+
+# Linux
+apt install lcdf-typetools
+# or compile from source
+
+# Windows
+# Requires MSYS2 or WSL
+```
+
+### Fontisan
+
+```bash
+# All platforms
+gem install fontisan
+```
+
+## Use Case Recommendations
+
+### Use Fontisan When:
+
+- You need validation
+- You need WOFF/WOFF2
+- You need collection support
+- You want minimal installation
+- You need Type 1 → OTF conversion
+
+### Use lcdf-typetools When:
+
+- You need t1dotlessj
+- You need t1lint
+- You're in a C++ environment
+- You have existing workflows
+
+## Code Comparison
+
+### Get Font Info
+
+```bash
+# otfinfo
+otfinfo -i font.ttf | grep Family
+
+# Fontisan
+fontisan info font.ttf --format json | jq '.family'
+```
+
+### Convert TTF to OTF
+
+```bash
+# ttf2otf
+ttf2otf font.ttf font.otf
+
+# Fontisan
+fontisan convert font.ttf --to otf --output font.otf
+```
+
+### Convert OTF to Type 1
+
+```bash
+# cfftot1
+cfftot1 font.otf font.pfb
+
+# Fontisan
+fontisan convert font.otf --to type1 --output font.pfb
+```
+
+## Conclusion
+
+| Need | Recommendation |
+|------|----------------|
+| Ruby environment | Fontisan |
+| Validation | Fontisan |
+| WOFF/WOFF2 | Fontisan |
+| Collections | Fontisan |
+| t1dotlessj | lcdf-typetools |
+| Type 1 linting | lcdf-typetools |
+| Minimal installation | Fontisan |