fontisan 0.2.13 → 0.2.16

data/docs/guide/formats/type1.md

@@ -0,0 +1,118 @@
+---
+title: Type 1 (PFB/PFA)
+---
+
+# Type 1 (PFB/PFA)
+
+Adobe Type 1 fonts are legacy PostScript fonts.
+
+## Overview
+
+- **Curve Type**: Cubic Bézier
+- **Hinting**: PostScript hints
+- **Formats**: PFB (binary), PFA (ASCII)
+
+## File Formats
+
+| Format | Extension | Description |
+|--------|-----------|-------------|
+| PFB | .pfb | Binary format |
+| PFA | .pfa | ASCII format |
+
+## Structure
+
+Type 1 fonts contain:
+
+1. **Font Dictionary** — Font info, encoding
+2. **Private Dictionary** — Hinting parameters
+3. **CharStrings** — Glyph outlines
+4. **Subroutines** — Reusable outline segments
+
+## Encryption
+
+Type 1 fonts use encryption:
+
+| Section | Key |
+|---------|-----|
+| eexec | 55665 |
+| CharStrings | 4330 |
+
+Fontisan handles decryption automatically.
+
+## Loading
+
+```ruby
+font = Fontisan::FontLoader.load('font.pfb')
+
+# Access font info
+puts "Family: #{font.family_name}"
+puts "Glyphs: #{font.glyph_count}"
+```
+
+## CharStrings
+
+```ruby
+# Type 1 CharStrings use operators
+# hstem, vstem, moveto, lineto, curveto, etc.
+
+font.charstrings.each do |glyph_name, charstring|
+  puts "#{glyph_name}: #{charstring.length} bytes"
+end
+```
+
+## seac Composites
+
+Type 1 supports composite characters via `seac`:
+
+```
+# Example: é = e + acute accent
+# seac references two glyphs by name
+```
+
+When converting to CFF, seac must be expanded (CFF doesn't support it).
+
+## Converting
+
+### Type 1 to OTF
+
+```bash
+fontisan convert font.pfb --to otf --output font.otf
+```
+
+### Type 1 to TTF
+
+```bash
+fontisan convert font.pfb --to ttf --output font.ttf
+```
+
+### With Unicode Generation
+
+```bash
+# Generate Unicode mappings from glyph names
+fontisan convert font.pfb --to otf --generate-unicode --output font.otf
+```
+
+## Characteristics
+
+### Advantages
+
+- **Print workflows** — PostScript native
+- **High quality** — Professional fonts
+- **Cubic curves** — Fewer points
+
+### Limitations
+
+- **Legacy format** — Modern systems prefer OTF
+- **Limited Unicode** — Requires glyph name mapping
+- **No native Unicode** — Must be generated
+
+## seac Expansion
+
+seac (Standard Encoding Accented Character) must be expanded for CFF:
+
+```ruby
+# Fontisan automatically expands seac during conversion
+options = Fontisan::ConversionOptions.new(
+  opening: { decompose_composites: true }
+)
+```

data/docs/guide/formats/woff.md

@@ -0,0 +1,115 @@
+---
+title: WOFF & WOFF2
+---
+
+# WOFF & WOFF2
+
+Web Open Font Format (WOFF and WOFF2) are optimized for web delivery.
+
+## Overview
+
+| Format | Compression | Browser Support |
+|--------|-------------|-----------------|
+| WOFF | zlib | All modern browsers |
+| WOFF2 | brotli | Modern browsers |
+
+## WOFF2 Benefits
+
+- 30-50% smaller than TTF/OTF
+- Preprocessing transforms for better compression
+- Modern browser support
+
+## Converting to WOFF
+
+```bash
+# From TTF
+fontisan convert font.ttf --to woff --output font.woff
+
+# From OTF
+fontisan convert font.otf --to woff --output font.woff
+```
+
+## Converting to WOFF2
+
+```bash
+# From TTF
+fontisan convert font.ttf --to woff2 --output font.woff2
+
+# From OTF
+fontisan convert font.otf --to woff2 --output font.woff2
+
+# From Type 1
+fontisan convert font.pfb --to woff2 --output font.woff2
+```
+
+## API Usage
+
+```ruby
+options = Fontisan::ConversionOptions.from_preset(:web_optimized)
+# From: :otf, To: :woff2
+# generating: { compression: "brotli", transform_tables: true }
+
+Fontisan::FontWriter.write(font, 'font.woff2', options: options)
+```
+
+## Compression Options
+
+### brotli (WOFF2)
+
+```ruby
+generating: { compression: "brotli" }
+```
+
+Best compression ratio.
+
+### zlib (WOFF)
+
+```ruby
+generating: { compression: "zlib" }
+```
+
+Wide compatibility.
+
+## Table Transforms
+
+WOFF2 supports table transformations:
+
+| Table | Transform |
+|-------|-----------|
+| glyf | Combined with loca |
+| hmtx | Combined with hhea |
+| CFF | De-subroutinization |
+
+```ruby
+options = Fontisan::ConversionOptions.new(
+  to: :woff2,
+  generating: { transform_tables: true }
+)
+```
+
+## Converting from WOFF
+
+```bash
+# WOFF to TTF
+fontisan convert font.woff --to ttf --output font.ttf
+
+# WOFF2 to OTF
+fontisan convert font.woff2 --to otf --output font.otf
+```
+
+## Browser Support
+
+| Browser | WOFF | WOFF2 |
+|---------|------|-------|
+| Chrome | 5+ | 36+ |
+| Firefox | 3.6+ | 35+ |
+| Safari | 5.1+ | 12+ |
+| Edge | All | 14+ |
+| IE | 9+ | — |
+
+## Best Practices
+
+1. **Use WOFF2 primarily** — Best compression
+2. **Provide WOFF fallback** — For older browsers
+3. **Keep original** — For editing
+4. **Preserve metadata** — Unless stripping for size

data/docs/guide/hinting/autohint.md

@@ -0,0 +1,141 @@
+---
+title: Autohint
+---
+
+# Autohint
+
+Fontisan supports automatic hint generation for fonts without hints or when converting between formats.
+
+## Overview
+
+Autohinting generates hint data automatically based on glyph outlines. This is useful when:
+
+- Source font lacks hints
+- Converting between incompatible hint systems
+- Improving rendering quality
+
+## CLI Usage
+
+```bash
+# Enable autohinting during conversion
+fontisan convert font.ttf --to otf --autohint --output font.otf
+
+# With specific hinting mode
+fontisan convert font.ttf --to otf --autohint --hinting-mode auto
+```
+
+## API Usage
+
+```ruby
+options = Fontisan::ConversionOptions.new(
+  opening: { autohint: true },
+  generating: { hinting_mode: "auto" }
+)
+
+converter = Fontisan::Converters::OutlineConverter.new
+result = converter.convert(font, options: options)
+```
+
+## Hinting Modes
+
+| Mode | Description | Use Case |
+|------|-------------|----------|
+| `preserve` | Keep original hints | Same-format conversions |
+| `auto` | Apply automatic hinting | Cross-format, missing hints |
+| `none` | Remove all hints | Smallest file size |
+| `full` | Full hint conversion | Maximum quality |
+
+## When to Use Autohint
+
+### Use Autohint When:
+
+- Converting TTF to OTF (different hint systems)
+- Converting OTF to TTF (different hint systems)
+- Source font has no hints
+- Source hints are corrupt or incomplete
+
+### Don't Use Autohint When:
+
+- Converting same format (TTF → TTF, OTF → OTF)
+- Source has good TrueType instructions
+- Source has good PostScript hints
+- Target application doesn't use hints
+
+## Autohint Process
+
+### For TrueType Output
+
+1. Analyze glyph outlines
+2. Detect stem widths and positions
+3. Generate CVT table with common values
+4. Create prep program with basic setup
+5. Leave fpgm empty (no glyph programs)
+
+### For OpenType Output
+
+1. Analyze glyph outlines
+2. Detect blue zones (baseline, x-height, cap height)
+3. Detect stem widths
+4. Generate Private DICT parameters
+5. Create stem hints in CharStrings
+
+## Quality
+
+### Autohint Limitations
+
+- **No glyph-specific instructions** — Only global hints
+- **May not match hand-tuned hints** — Quality varies
+- **Better than no hints** — Generally improves rendering
+
+### Comparison
+
+| Source | Autohint | Hand-Tuned |
+|--------|----------|------------|
+| Quality | Good | Best |
+| Consistency | High | Varies |
+| Time | Fast | Slow |
+| Cost | Free | Expensive |
+
+## Examples
+
+### Convert with Autohint
+
+```bash
+# Type 1 to OTF with autohint
+fontisan convert font.pfb --to otf --autohint --output font.otf
+```
+
+### Remove and Regenerate Hints
+
+```bash
+# Remove existing hints, add autohints
+fontisan convert font.ttf --to ttf --hinting-mode none --autohint --output font-rehinted.ttf
+```
+
+### Batch Processing
+
+```ruby
+Dir.glob('fonts/*.ttf').each do |input|
+  output = input.sub('.ttf', '-hinted.ttf')
+  options = Fontisan::ConversionOptions.new(
+    opening: { autohint: true },
+    generating: { hinting_mode: "auto" }
+  )
+
+  font = Fontisan::FontLoader.load(input)
+  converter = Fontisan::Converters::OutlineConverter.new
+  result = converter.convert(font, options: options)
+  Fontisan::FontWriter.write(result, output)
+end
+```
+
+## Testing Hints
+
+After autohinting, test rendering quality:
+
+```bash
+# Generate sample images at small sizes
+fontisan render font-hinted.ttf --size 8 --output sample-8pt.png
+fontisan render font-hinted.ttf --size 10 --output sample-10pt.png
+fontisan render font-hinted.ttf --size 12 --output sample-12pt.png
+```

data/docs/guide/hinting/conversion.md

@@ -0,0 +1,161 @@
+---
+title: Hint Conversion
+---
+
+# Hint Conversion
+
+Fontisan provides bidirectional hint conversion between TrueType and PostScript formats.
+
+## Overview
+
+| Direction | From | To | Process |
+|-----------|------|-----|---------|
+| TTF → OTF | TrueType instructions | PostScript hints | Analyze bytecode |
+| OTF → TTF | PostScript hints | TrueType instructions | Generate bytecode |
+
+## TTF → OTF Conversion
+
+### Process
+
+```
+TrueType Font → Instruction Analysis → PostScript Parameters → CFF Table
+   (Input)       (prep/fpgm/cvt)      (Hint Dict)        (Output)
+```
+
+### Analysis Steps
+
+1. Parse prep (Control Value Program) bytecode
+2. Analyze fpgm (Font Program) for complexity indicators
+3. Extract blue zones from CVT (Control Value Table) values
+4. Extract stem widths and alignment zones
+
+### Generated Parameters
+
+| Parameter | Source |
+|-----------|--------|
+| `blue_scale` | CVT analysis |
+| `std_hw` | CVT[0] (standard horizontal stem) |
+| `std_vw` | CVT[1] (standard vertical stem) |
+| `stem_snap_h` | CVT analysis |
+| `stem_snap_v` | CVT analysis |
+| `blue_values` | CVT analysis (baseline, cap) |
+| `other_blues` | CVT analysis (descender) |
+
+### CLI
+
+```bash
+fontisan convert font.ttf --to otf --hinting-mode preserve
+```
+
+### API
+
+```ruby
+converter = Fontisan::Converters::HintConverter.new
+
+# Convert TrueType hints to PostScript
+ps_hints = converter.truetype_to_postscript(font)
+
+# Result contains:
+# {
+#   blue_scale: 0.039625,
+#   std_hw: 80,
+#   std_vw: 100,
+#   blue_values: [-20, 0, 700, 720],
+#   stem_snap_h: [80, 90],
+#   stem_snap_v: [100, 110]
+# }
+```
+
+## OTF → TTF Conversion
+
+### Process
+
+```
+OTF Font → Parameter Extraction → Instruction Generation → TrueType Tables
+ (Input)    (CFF Private Dict)    (prep/fpgm/cvt)        (Output)
+```
+
+### Generation Steps
+
+1. Generate prep program with CVT cut-in, single width settings
+2. Build CVT table with stem widths and blue zone values
+3. Create fpgm program (typically empty for converted fonts)
+4. Encode instructions using optimal PUSH opcodes
+
+### Generated Tables
+
+| Table | Content |
+|-------|---------|
+| `prep` | Control Value Program with hint setup |
+| `cvt` | Control Value Table with stems and blue zones |
+| `fpgm` | Font Program (empty for converted fonts) |
+
+### CLI
+
+```bash
+fontisan convert font.otf --to ttf --hinting-mode preserve
+```
+
+### API
+
+```ruby
+converter = Fontisan::Converters::HintConverter.new
+
+# Convert PostScript hints to TrueType
+ttf_tables = converter.postscript_to_truetype(font)
+
+# Result contains:
+# {
+#   prep: "\xB0\x11\x1D",  # Bytecode
+#   cvt: [80, 100, -20, 0, 700, 720],
+#   fpgm: ""
+# }
+```
+
+## Round-Trip Conversion
+
+Fontisan ensures hint integrity through round-trip conversion:
+
+```
+Original PS Hints → TrueType → PostScript → Validation
+     (Input)         (Convert)   (Convert)    (Verify)
+```
+
+### Round-Trip Guarantees
+
+- CVT values preserved (sorted and deduplicated)
+- Standard widths (std_hw, std_vw) maintained
+- Blue zone values retained
+- <10% loss tolerance for approximations
+
+### Known Limitations
+
+- CVT sorting may change positions (optimization trade-off)
+- blue_scale not perfectly round-trippable (conversion approximation)
+- Standard widths extracted from CVT[0] and CVT[1] positions
+
+## Example
+
+```ruby
+# Round-trip test
+font = Fontisan::FontLoader.load('font.otf')
+original_hints = font.tables['CFF'].top_dicts.first[:private]
+
+# Convert to TrueType
+ttf_converter = Fontisan::Converters::HintConverter.new
+ttf_tables = ttf_converter.postscript_to_truetype(font)
+
+# Convert back to PostScript
+ps_hints = ttf_converter.truetype_to_postscript(ttf_font)
+
+# Compare
+puts "Original std_hw: #{original_hints[:std_hw]}"
+puts "Round-trip std_hw: #{ps_hints[:std_hw]}"
+```
+
+## Best Practices
+
+1. **Test round-trip** — Verify hint preservation
+2. **Use autohint for cross-format** — Consider `--hinting-mode auto`
+3. **Validate after conversion** — Check hint validity
+4. **Test rendering** — Verify visual quality at small sizes

data/docs/guide/hinting/index.md

@@ -0,0 +1,86 @@
+---
+title: Font Hinting Overview
+---
+
+# Font Hinting Overview
+
+Fontisan provides comprehensive support for font hints, including extraction, conversion, validation, and preservation. Hints are rendering instructions embedded in fonts that improve appearance at small sizes and low resolutions.
+
+## Hinting Systems
+
+Fontisan supports two hinting systems:
+
+| System | Format | Storage | Type |
+|--------|--------|---------|------|
+| TrueType | TTF | prep, fpgm, cvt tables | Bytecode instructions |
+| PostScript | OTF | CFF Private DICT | Declarative hints |
+
+### TrueType Instructions
+
+Bytecode-based hints using instruction opcodes:
+
+- `SSW` — Set Single Width
+- `SCVTCI` — Set CVT Cut-In
+- `WCVTP` — Write CVT in Pixels
+- And many more...
+
+Stored in:
+- `prep` — Control Value Program
+- `fpgm` — Font Program
+- `cvt` — Control Value Table
+
+### PostScript Hints
+
+Declarative hints using operators:
+
+- `hstem` — Horizontal stem hints
+- `vstem` — Vertical stem hints
+- `hintmask` — Hint activation mask
+
+Stored in CFF Private dictionaries.
+
+## Features
+
+- **Bidirectional Conversion** — Convert hints between TrueType and PostScript
+- **Hint Extraction** — Extract existing hints from TTF and OTF fonts
+- **Hint Application** — Apply hints during format conversion
+- **Validation** — Comprehensive validation of hint data
+- **Round-Trip Preservation** — Maintain hint integrity during conversion cycles
+
+## Guides
+
+- [TrueType Hinting](/guide/hinting/truetype) — TrueType instruction details
+- [PostScript Hinting](/guide/hinting/postscript) — CFF hint parameters
+- [Hint Conversion](/guide/hinting/conversion) — Bidirectional conversion
+- [Autohint](/guide/hinting/autohint) — Automatic hinting
+
+## Quick Start
+
+### Check for Hints
+
+```ruby
+font = Fontisan::FontLoader.load('font.ttf')
+
+# Check TrueType hints
+if font.tables['prep'] || font.tables['fpgm']
+  puts "TrueType hints present"
+end
+
+# Check PostScript hints
+if cff = font.tables['CFF']
+  private_dict = cff.top_dicts.first[:private]
+  if private_dict[:blue_values]
+    puts "PostScript hints present"
+  end
+end
+```
+
+### Convert with Hints
+
+```bash
+# Preserve hints during conversion
+fontisan convert font.ttf --to otf --hinting-mode preserve
+
+# Apply autohinting
+fontisan convert font.ttf --to otf --autohint --hinting-mode auto
+```