fontisan 0.2.13 → 0.2.16

data/docs/guide/conversion/ttf-otf.md

@@ -0,0 +1,184 @@
+---
+title: TTF ↔ OTF Conversion
+---
+
+# TTF ↔ OTF Conversion
+
+Converting between TrueType (TTF) and OpenType/CFF (OTF) formats involves curve conversion and hinting system changes.
+
+## Overview
+
+| Source | Target | Curve Type | Hinting System |
+|--------|--------|------------|----------------|
+| TTF | OTF | Quadratic → Cubic | TrueType → CFF |
+| OTF | TTF | Cubic → Quadratic | CFF → TrueType |
+
+## TTF → OTF
+
+Convert TrueType fonts to OpenType/CFF format.
+
+### Recommended Options
+
+```ruby
+Fontisan::ConversionOptions.recommended(from: :ttf, to: :otf)
+# Returns:
+# opening: { convert_curves: true, scale_to_1000: true, autohint: true,
+#           decompose_composites: false, store_custom_tables: true }
+# generating: { hinting_mode: "auto", decompose_on_output: true }
+```
+
+### CLI
+
+```bash
+# Basic conversion
+fontisan convert font.ttf --to otf --output font.otf
+
+# With autohint
+fontisan convert font.ttf --to otf --autohint --output font.otf
+
+# Show options that will be used
+fontisan convert font.ttf --to otf --show-options
+```
+
+### Key Considerations
+
+- **Curve conversion**: Quadratic → Cubic (mathematically exact, but may increase point count)
+- **Hinting**: TrueType instructions → CFF hints (lossy conversion)
+- **Scaling**: Typically 2048 UPM → 1000 UPM
+
+### Limitations
+
+- TrueType hinting instructions are NOT converted to CFF hints
+- GSUB/GPOS features preserved but table format changes
+
+## OTF → TTF
+
+Convert OpenType/CFF fonts to TrueType format.
+
+### Recommended Options
+
+```ruby
+Fontisan::ConversionOptions.recommended(from: :otf, to: :ttf)
+# Returns:
+# opening: { decompose_composites: false, read_all_records: true,
+#           interpret_ot: true, store_custom_tables: true,
+#           store_native_hinting: false }
+# generating: { hinting_mode: "full", reencode_first_256: false }
+```
+
+### CLI
+
+```bash
+# Basic conversion
+fontisan convert font.otf --to ttf --output font.ttf
+
+# With full hinting
+fontisan convert font.otf --to ttf --hinting-mode full --output font.ttf
+```
+
+### Key Considerations
+
+- **Curve conversion**: Cubic → Quadratic (requires approximation)
+- **Hinting**: CFF hints → TrueType instructions (lossy conversion)
+- **OpenType features**: Interpreted before conversion
+
+### Limitations
+
+- CFF cubic curves must be approximated as TrueType quadratic curves
+- Multiple quadratic curves may be needed for accuracy
+- Some precision loss in curve approximation is unavoidable
+
+## Same-Format Copy
+
+### TTF → TTF
+
+```ruby
+Fontisan::ConversionOptions.recommended(from: :ttf, to: :ttf)
+# opening: { convert_curves: false, scale_to_1000: false,
+#            decompose_composites: false, autohint: false,
+#            store_custom_tables: true, store_native_hinting: true }
+# generating: { hinting_mode: "preserve", write_custom_tables: true,
+#              optimize_tables: true }
+```
+
+Use cases: Copy with optimization, metadata updates
+
+### OTF → OTF
+
+```ruby
+Fontisan::ConversionOptions.recommended(from: :otf, to: :otf)
+# opening: { decompose_composites: false, store_custom_tables: true,
+#            interpret_ot: true }
+# generating: { hinting_mode: "preserve", decompose_on_output: false,
+#              write_custom_tables: true, optimize_tables: true }
+```
+
+Use cases: Copy with optimization, metadata updates
+
+## Curve Conversion Details
+
+### Quadratic → Cubic (TTF → OTF)
+
+This conversion is mathematically exact:
+
+```ruby
+# TrueType quadratic Bézier
+# P0, P1, P2 where P1 is the control point
+
+# Converts to cubic Bézier
+# P0, C1, C2, P2 where:
+# C1 = P0 + (2/3)(P1 - P0)
+# C2 = P2 + (2/3)(P1 - P2)
+```
+
+Result: Exact representation, but may increase point count.
+
+### Cubic → Quadratic (OTF → TTF)
+
+This conversion requires approximation:
+
+```ruby
+# Cubic Bézier cannot be exactly represented as quadratic
+# Requires splitting into multiple quadratic curves
+
+# Approximation tolerance controls accuracy
+options = Fontisan::ConversionOptions.new(
+  curve_tolerance: 0.5  # Lower = more accurate, more points
+)
+```
+
+Result: Some precision loss unavoidable.
+
+## Examples
+
+### Batch Conversion
+
+```ruby
+# Convert all TTF files in a directory
+Dir.glob('fonts/*.ttf').each do |input|
+  output = input.sub('.ttf', '.otf')
+  Fontisan.convert(input, output_format: :otf, output_path: output)
+end
+```
+
+### With Custom Options
+
+```ruby
+options = Fontisan::ConversionOptions.new(
+  from: :ttf,
+  to: :otf,
+  opening: {
+    convert_curves: true,
+    scale_to_1000: true,
+    autohint: true
+  },
+  generating: {
+    hinting_mode: 'auto',
+    optimize_tables: true
+  }
+)
+
+converter = Fontisan::Converters::OutlineConverter.new
+result = converter.convert(font, options: options)
+Fontisan::FontWriter.write(result, 'output.otf')
+```

data/docs/guide/conversion/type1.md

@@ -0,0 +1,208 @@
+---
+title: Type 1 to Modern Formats
+---
+
+# Type 1 to Modern Formats
+
+Adobe Type 1 fonts (PFB/PFA) are legacy PostScript fonts. Fontisan provides comprehensive support for converting them to modern formats.
+
+## Overview
+
+Type 1 fonts use:
+- **Cubic Bézier curves** — Compatible with CFF/OpenType
+- **PostScript hints** — Different from TrueType instructions
+- **Custom encoding** — May lack Unicode mappings
+
+## Type 1 → OTF
+
+Convert Type 1 fonts to OpenType/CFF format.
+
+### Recommended Options
+
+```ruby
+Fontisan::ConversionOptions.recommended(from: :type1, to: :otf)
+# Returns:
+# opening: { decompose_composites: false, generate_unicode: true }
+# generating: { hinting_mode: "none", decompose_on_output: true }
+```
+
+### CLI
+
+```bash
+# Basic conversion
+fontisan convert font.pfb --to otf --output font.otf
+
+# With preset
+fontisan convert font.pfb --to otf --preset type1_to_modern --output font.otf
+
+# With Unicode generation
+fontisan convert font.pfb --to otf --generate-unicode --output font.otf
+```
+
+### Key Considerations
+
+- **Unicode**: Generated from Adobe Glyph List
+- **CharStrings**: Type 1 → CFF format (direct conversion)
+- **Hinting**: PostScript hints preserved in CFF
+- **seac composites**: Must be expanded (CFF doesn't support seac)
+
+## Type 1 → TTF
+
+Convert Type 1 fonts to TrueType format.
+
+### Recommended Options
+
+```ruby
+Fontisan::ConversionOptions.recommended(from: :type1, to: :ttf)
+# Returns:
+# opening: { decompose_composites: false, generate_unicode: true }
+# generating: { hinting_mode: "full" }
+```
+
+### Workflow
+
+```
+Type 1 → CFF (OTF) → TTF
+```
+
+### Key Considerations
+
+- Two-step conversion compounds approximation errors
+- Curve conversion: CFF cubic → TrueType quadratic
+- Unicode: Generated from glyph names
+
+### CLI
+
+```bash
+fontisan convert font.pfb --to ttf --autohint --output font.ttf
+```
+
+## OTF → Type 1
+
+Convert OpenType fonts back to Type 1 for legacy systems.
+
+### Recommended Options
+
+```ruby
+Fontisan::ConversionOptions.recommended(from: :otf, to: :type1)
+# opening: { decompose_composites: false }
+# generating: { write_pfm: true, write_afm: true, write_inf: true,
+#              select_encoding_automatically: true, hinting_mode: "preserve",
+#              decompose_on_output: false }
+```
+
+### CLI
+
+```bash
+fontisan convert font.otf --to type1 --output font.pfb
+```
+
+### Limitations
+
+- Reverse conversion from CFF to Type 1
+- Modern OpenType features (GPOS, GSUB variations) lost in Type 1
+- CFF hints may not translate exactly to Type 1 hints
+
+## Type 1 → Type 1 (Copy)
+
+Re-encode Type 1 font or regenerate metrics files.
+
+### Recommended Options
+
+```ruby
+Fontisan::ConversionOptions.recommended(from: :type1, to: :type1)
+# opening: { decompose_composites: false, generate_unicode: true }
+# generating: { write_pfm: true, write_afm: true, write_inf: true,
+#              select_encoding_automatically: true, hinting_mode: "preserve" }
+```
+
+### CLI
+
+```bash
+# Regenerate metrics files
+fontisan convert font.pfb --to type1 --write-pfm --write-afm --output font-copy.pfb
+```
+
+## seac Composite Handling
+
+Type 1 fonts use `seac` (Standard Encoding Accented Character) for composite glyphs. CFF doesn't support seac, so these must be expanded.
+
+```ruby
+# seac composites are automatically decomposed
+options = Fontisan::ConversionOptions.new(
+  opening: { decompose_composites: true }
+)
+```
+
+### What seac Does
+
+```
+# seac combines two glyphs:
+# Example: é = e + ´ (acute accent)
+#
+# In Type 1:
+# /eacute { seac (e) (acute) } def
+#
+# In CFF/OTF:
+# Must be expanded to actual outlines
+```
+
+## Presets
+
+### type1_to_modern
+
+Optimize Type 1 fonts for modern use:
+
+```ruby
+Fontisan::ConversionOptions.from_preset(:type1_to_modern)
+# From: :type1, To: :otf
+# opening: { generate_unicode: true, decompose_composites: false }
+# generating: { hinting_mode: "preserve", decompose_on_output: true }
+```
+
+Use cases:
+- Modernizing legacy Type 1 fonts
+- Preparing fonts for web use
+- Converting fonts for modern applications
+
+### modern_to_type1
+
+Convert modern fonts back to Type 1:
+
+```ruby
+Fontisan::ConversionOptions.from_preset(:modern_to_type1)
+# From: :otf, To: :type1
+# opening: { convert_curves: true, scale_to_1000: true,
+#           autohint: true, decompose_composites: false,
+#           store_custom_tables: false }
+# generating: { write_pfm: true, write_afm: true, write_inf: true,
+#              select_encoding_automatically: true,
+#              hinting_mode: "preserve" }
+```
+
+Use cases:
+- Legacy system compatibility
+- Font distribution for older applications
+- Working with Type 1 workflows
+
+## Examples
+
+### Convert Type 1 to Web Font
+
+```bash
+# Direct to WOFF2
+fontisan convert font.pfb --to woff2 --output font.woff2 --preset type1_to_modern
+
+# With custom options
+fontisan convert font.pfb --to woff2 --output font.woff2 \
+  --generate-unicode --optimize-tables
+```
+
+### Batch Convert Directory
+
+```ruby
+Dir.glob('legacy/*.pfb').each do |input|
+  output = input.sub('.pfb', '.otf').sub('legacy/', 'modern/')
+  Fontisan.convert(input, output_format: :otf, output_path: output)
+end
+```

data/docs/guide/conversion/web.md

@@ -0,0 +1,240 @@
+---
+title: Web Font Formats
+---
+
+# Web Font Formats
+
+Fontisan supports conversion to web-optimized formats (WOFF and WOFF2) for optimal web delivery.
+
+## Overview
+
+| Format | Compression | Browser Support | Use Case |
+|--------|-------------|-----------------|----------|
+| WOFF | zlib | All modern browsers | Wide compatibility |
+| WOFF2 | brotli | Modern browsers | Smallest size |
+
+## WOFF2
+
+WOFF2 provides 30-50% smaller files than TTF/OTF.
+
+### Conversion
+
+```bash
+# Basic WOFF2 conversion
+fontisan convert font.ttf --to woff2 --output font.woff2
+
+# From any format
+fontisan convert font.otf --to woff2 --output font.woff2
+fontisan convert font.pfb --to woff2 --output font.woff2
+```
+
+### Recommended Options
+
+```ruby
+Fontisan::ConversionOptions.from_preset(:web_optimized)
+# From: :otf, To: :woff2
+# opening: {}
+# generating: { compression: "brotli", transform_tables: true,
+#              optimize_tables: true, preserve_metadata: true }
+```
+
+### WOFF2 Benefits
+
+- 30-50% smaller than TTF/OTF
+- Broader browser support
+- Preprocessing transforms for better compression
+
+## WOFF
+
+WOFF provides wider compatibility with older browsers.
+
+### Conversion
+
+```bash
+# Basic WOFF conversion
+fontisan convert font.ttf --to woff --output font.woff
+```
+
+### Options
+
+```ruby
+options = Fontisan::ConversionOptions.new(
+  to: :woff,
+  generating: {
+    compression: "zlib",
+    preserve_metadata: true,
+    add_private_data: false
+  }
+)
+```
+
+## web_optimized Preset
+
+Optimize fonts for web delivery:
+
+```ruby
+Fontisan::ConversionOptions.from_preset(:web_optimized)
+# From: :otf, To: :woff2
+# opening: {}
+# generating: { compression: "brotli", transform_tables: true,
+#              optimize_tables: true, preserve_metadata: true }
+```
+
+### Use Cases
+
+- Web font delivery
+- Reducing page load time
+- Bandwidth optimization
+
+## Type 1 → Web Fonts
+
+Convert legacy Type 1 fonts to web formats.
+
+### Workflow
+
+```
+Type 1 → OTF → WOFF2
+```
+
+### CLI
+
+```bash
+# Direct conversion
+fontisan convert font.pfb --to woff2 --output font.woff2 --preset type1_to_modern
+
+# Step by step
+fontisan convert font.pfb --to otf --output font.otf --generate-unicode
+fontisan convert font.otf --to woff2 --output font.woff2
+```
+
+### Options
+
+```ruby
+# Via OTF intermediate
+options = Fontisan::ConversionOptions.new(
+  opening: { decompose_composites: false, generate_unicode: true },
+  generating: { compression: "brotli" }  # WOFF2
+  # OR: generating: { compression: "zlib" }    # WOFF
+)
+```
+
+## Compression Options
+
+### brotli (WOFF2)
+
+```ruby
+generating: { compression: "brotli" }
+```
+
+- Best compression ratio
+- Requires modern browsers
+- Transforms tables for better compression
+
+### zlib (WOFF)
+
+```ruby
+generating: { compression: "zlib" }
+```
+
+- Good compression
+- Wide browser support
+- No table transforms
+
+### none
+
+```ruby
+generating: { compression: "none" }
+```
+
+- No compression
+- For debugging
+
+## Table Transforms
+
+WOFF2 supports table transformations for better compression:
+
+| Table | Transform |
+|-------|-----------|
+| glyf | Combined with loca, bbox deltas |
+| hmtx | Combined with hhea |
+| CFF | De-subroutinization |
+
+```ruby
+options = Fontisan::ConversionOptions.new(
+  to: :woff2,
+  generating: { transform_tables: true }
+)
+```
+
+## Metadata Handling
+
+### Preserve Metadata
+
+```bash
+fontisan convert font.ttf --to woff2 --preserve-metadata
+```
+
+Keeps copyright, license, and other metadata intact.
+
+### Strip Metadata
+
+```bash
+fontisan convert font.ttf --to woff2 --strip-metadata
+```
+
+Removes metadata for smaller file size (check license first).
+
+## Examples
+
+### Complete Web Font Workflow
+
+```ruby
+require 'fontisan'
+
+# Load source
+font = Fontisan::FontLoader.load('source.ttf')
+
+# Create WOFF2
+woff2_options = Fontisan::ConversionOptions.from_preset(:web_optimized)
+Fontisan::FontWriter.write(font, 'font.woff2', options: woff2_options)
+
+# Create WOFF for older browsers
+woff_options = Fontisan::ConversionOptions.new(
+  to: :woff,
+  generating: { compression: "zlib", preserve_metadata: true }
+)
+Fontisan::FontWriter.write(font, 'font.woff', options: woff_options)
+```
+
+### Batch Web Conversion
+
+```bash
+# Convert all TTF files to WOFF2
+for f in fonts/*.ttf; do
+  fontisan convert "$f" --to woff2 --output "web/$(basename "${f%.ttf}.woff2")"
+done
+```
+
+### Compare File Sizes
+
+```bash
+# Check file sizes
+ls -la font.ttf font.woff font.woff2
+
+# Example output:
+# -rw-r--r--  font.ttf    124,500 bytes
+# -rw-r--r--  font.woff    98,200 bytes   (21% smaller)
+# -rw-r--r--  font.woff2   62,300 bytes   (50% smaller)
+```
+
+## Browser Support
+
+| Browser | WOFF | WOFF2 |
+|---------|------|-------|
+| Chrome | 5+ | 36+ |
+| Firefox | 3.6+ | 35+ |
+| Safari | 5.1+ | 12+ |
+| Edge | All | 14+ |
+| IE | 9+ | — |
+
+For maximum compatibility, provide both WOFF and WOFF2.

data/docs/guide/conversion.md

@@ -0,0 +1,39 @@
+# Font Conversion
+
+Fontisan supports conversion between various font formats.
+
+## Supported Formats
+
+| Input | Output Formats |
+|-------|---------------|
+| TrueType (.ttf) | OTF, WOFF, WOFF2 |
+| OpenType (.otf) | TTF, WOFF, WOFF2 |
+| Type 1 (.pfb) | TTF, OTF, WOFF, WOFF2 |
+| WOFF | TTF, OTF |
+| WOFF2 | TTF, OTF |
+
+## Basic Conversion
+
+```ruby
+require 'fontisan'
+
+# Convert TTF to WOFF2
+Fontisan.convert('font.ttf', output_format: :woff2)
+
+# Convert with custom output path
+Fontisan.convert('font.ttf', output_path: 'output/font.woff2')
+```
+
+## Batch Conversion
+
+```ruby
+# Convert multiple files
+fonts = Dir.glob('fonts/*.ttf')
+fonts.each do |font|
+  Fontisan.convert(font, output_format: :otf)
+end
+```
+
+## Related
+
+- [WOFF/WOFF2 Formats](/guide/woff) - Details on web font formats