fontisan 0.2.13 → 0.2.16

data/docs/guide/formats/collections.md

@@ -0,0 +1,147 @@
+---
+title: Font Collections
+---
+
+# Font Collections (TTC/OTC)
+
+Font collections pack multiple fonts into a single file with shared tables.
+
+## Overview
+
+| Format | Description | Font Type |
+|--------|-------------|-----------|
+| TTC | TrueType Collection | TrueType fonts |
+| OTC | OpenType Collection | CFF/OpenType fonts |
+
+## Benefits
+
+- **Smaller total size** — Shared tables
+- **Simpler distribution** — One file
+- **Family organization** — Related fonts together
+
+## Shared Tables
+
+Collections share common tables:
+
+- `cmap` — Character mappings
+- `loca` — Glyph locations
+- `maxp` — Maximum profile
+- `name` — Font names
+- `post` — PostScript names
+
+## Listing Fonts
+
+### CLI
+
+```bash
+fontisan ls family.ttc
+
+# Collection: family.ttc
+# Fonts: 4
+#
+# 0. Family Regular
+#    PostScript: Family-Regular
+#    Glyphs: 268, Tables: 14
+#
+# 1. Family Bold
+#    PostScript: Family-Bold
+#    Glyphs: 268, Tables: 14
+```
+
+### API
+
+```ruby
+collection = Fontisan::FontLoader.load('family.ttc')
+
+collection.each_with_index do |font, index|
+  puts "#{index}. #{font.family_name} #{font.style}"
+end
+```
+
+## Extracting Fonts
+
+### CLI
+
+```bash
+# Extract all fonts
+fontisan unpack family.ttc --output-dir ./extracted
+
+# Extract specific font
+fontisan unpack family.ttc --index 0 --output regular.ttf
+
+# Extract with conversion
+fontisan unpack family.ttc --output-dir ./otf --format otf
+```
+
+### API
+
+```ruby
+collection = Fontisan::FontLoader.load('family.ttc')
+
+collection.each_with_index do |font, index|
+  output = "font-#{index}.ttf"
+  Fontisan::FontWriter.write(font, output)
+end
+```
+
+## Creating Collections
+
+### CLI
+
+```bash
+# Pack fonts into TTC
+fontisan pack regular.ttf bold.ttf italic.ttf --output family.ttc
+
+# Pack with deduplication
+fontisan pack *.ttf --output family.ttc --deduplicate
+
+# Pack as OTC
+fontisan pack regular.otf bold.otf --output family.otc
+```
+
+### API
+
+```ruby
+fonts = [
+  Fontisan::FontLoader.load('regular.ttf'),
+  Fontisan::FontLoader.load('bold.ttf'),
+  Fontisan::FontLoader.load('italic.ttf')
+]
+
+Fontisan::CollectionWriter.pack(fonts, 'family.ttc')
+```
+
+## Table Deduplication
+
+```bash
+# Deduplicate tables when packing
+fontisan pack *.ttf --output family.ttc --deduplicate
+```
+
+Benefits:
+- Smaller file size
+- Identical tables shared
+- Optimized storage
+
+## Converting Collections
+
+### TTC to OTC
+
+```bash
+fontisan convert family.ttc --to otc --output family.otc
+```
+
+### OTC to TTC
+
+```bash
+fontisan convert family.otc --to ttc --output family.ttc
+```
+
+## Apple dfont
+
+dfont supports mixed font types:
+
+```bash
+# Convert TTC to dfont
+fontisan convert family.ttc --to dfont --output family.dfont
+```

data/docs/guide/formats/dfont.md

@@ -0,0 +1,99 @@
+---
+title: Apple dfont
+---
+
+# Apple dfont
+
+Apple Data Fork Font (dfont) is a legacy Mac OS X format.
+
+## Overview
+
+- **Container**: Resource fork format in data fork
+- **Font Types**: TrueType, OpenType, or mixed
+- **Platform**: macOS specific
+
+## Structure
+
+dfont uses resource fork structure:
+- Resource map
+- Resource data
+- Multiple font resources
+
+## Loading
+
+```ruby
+font = Fontisan::FontLoader.load('font.dfont')
+
+# Access as collection
+if font.respond_to?(:each)
+  font.each do |f|
+    puts "#{f.family_name} #{f.style}"
+  end
+end
+```
+
+## Extracting
+
+### CLI
+
+```bash
+# List fonts in dfont
+fontisan ls font.dfont
+
+# Extract all
+fontisan unpack font.dfont --output-dir ./extracted
+```
+
+### API
+
+```ruby
+dfont = Fontisan::FontLoader.load('font.dfont')
+
+dfont.each_with_index do |font, index|
+  output = "font-#{index}.ttf"
+  Fontisan::FontWriter.write(font, output)
+end
+```
+
+## Converting
+
+### dfont to TTF
+
+```bash
+fontisan convert font.dfont --to ttf --output font.ttf
+```
+
+### dfont to OTF
+
+```bash
+fontisan convert font.dfont --to otf --output font.otf
+```
+
+### To dfont
+
+```bash
+# From TTC
+fontisan convert family.ttc --to dfont --output family.dfont
+
+# From individual fonts
+fontisan pack regular.ttf bold.ttf --output family.dfont
+```
+
+## Limitations
+
+- **macOS only** — Not cross-platform
+- **Legacy format** — Modern formats preferred
+- **Limited support** — Some tools don't read dfont
+
+## When to Use
+
+- **Legacy Mac fonts** — Converting old resources
+- **Resource fork recovery** — Extracting embedded fonts
+- **macOS compatibility** — When required
+
+## Modern Alternatives
+
+For new fonts, prefer:
+- **TTC** — TrueType Collection
+- **OTC** — OpenType Collection
+- **WOFF2** — Web delivery

data/docs/guide/formats/index.md

@@ -0,0 +1,65 @@
+---
+title: Font Formats Overview
+---
+
+# Font Formats Overview
+
+Fontisan supports a wide range of font formats.
+
+## Supported Formats
+
+### Modern Formats
+
+| Format | Extension | Description |
+|--------|-----------|-------------|
+| TrueType | .ttf | Standard TrueType font |
+| OpenType | .otf | CFF-based OpenType font |
+| WOFF | .woff | Web Open Font Format |
+| WOFF2 | .woff2 | Web Open Font Format 2 |
+
+### Legacy Formats
+
+| Format | Extension | Description |
+|--------|-----------|-------------|
+| Type 1 | .pfb, .pfa | Adobe Type 1 font |
+| dfont | .dfont | Apple Data Fork font |
+| TTC | .ttc | TrueType Collection |
+| OTC | .otc | OpenType Collection |
+
+### Other Formats
+
+| Format | Extension | Description |
+|--------|-----------|-------------|
+| SVG | .svg | SVG font |
+
+## Guides
+
+- [TrueType (TTF)](/guide/formats/ttf) — TrueType font format
+- [OpenType (OTF)](/guide/formats/otf) — OpenType/CFF format
+- [Type 1 (PFB/PFA)](/guide/formats/type1) — Adobe Type 1 fonts
+- [WOFF & WOFF2](/guide/formats/woff) — Web font formats
+- [Collections](/guide/formats/collections) — TTC and OTC collections
+- [Apple dfont](/guide/formats/dfont) — Apple legacy format
+- [SVG Fonts](/guide/formats/svg) — SVG-based fonts
+
+## Format Detection
+
+Fontisan automatically detects font format:
+
+```ruby
+# Works with any format
+font = Fontisan::FontLoader.load('font.ttf')
+font = Fontisan::FontLoader.load('font.otf')
+font = Fontisan::FontLoader.load('font.pfb')
+font = Fontisan::FontLoader.load('font.woff2')
+```
+
+## Conversion Matrix
+
+| From | To TTF | To OTF | To WOFF | To WOFF2 |
+|------|--------|--------|---------|----------|
+| TTF | ✓ | ✓ | ✓ | ✓ |
+| OTF | ✓ | ✓ | ✓ | ✓ |
+| Type 1 | ✓ | ✓ | ✓ | ✓ |
+| WOFF | ✓ | ✓ | ✓ | ✓ |
+| WOFF2 | ✓ | ✓ | ✓ | ✓ |

data/docs/guide/formats/otf.md

@@ -0,0 +1,103 @@
+---
+title: OpenType (OTF)
+---
+
+# OpenType (OTF)
+
+OpenType/CFF uses cubic Bézier curves in a Compact Font Format.
+
+## Overview
+
+- **Curve Type**: Cubic Bézier
+- **Hinting**: PostScript hints
+- **Storage**: CFF table
+
+## Key Tables
+
+| Table | Purpose |
+|-------|---------|
+| head | Font header |
+| hhea | Horizontal header |
+| maxp | Maximum profile |
+| name | Name records |
+| cmap | Character mapping |
+| CFF | Compact Font Format |
+| hmtx | Horizontal metrics |
+| post | PostScript names |
+| OS/2 | OS/2 metrics |
+| GSUB | Glyph substitution |
+| GPOS | Glyph positioning |
+
+## CFF Table Structure
+
+```ruby
+cff = font.tables['CFF']
+
+# Top DICT
+top_dict = cff.top_dicts.first
+
+# Name
+puts "Font name: #{cff.names.first}"
+
+# Private DICT
+private = top_dict[:private]
+puts "Blue values: #{private[:blue_values]}"
+puts "Std HW: #{private[:std_hw]}"
+```
+
+## CharStrings
+
+```ruby
+cff = font.tables['CFF']
+
+# Access CharStrings
+charstrings = cff.charstrings
+
+charstrings.each_with_index do |charstring, glyph_id|
+  puts "Glyph #{glyph_id}: #{charstring.length} operators"
+end
+```
+
+## Hinting
+
+OpenType fonts use PostScript hints:
+
+```ruby
+private = font.tables['CFF'].top_dicts.first[:private]
+
+# Blue zones
+puts "Blue values: #{private[:blue_values]}"
+puts "Other blues: #{private[:other_blues]}"
+
+# Stem widths
+puts "Std HW: #{private[:std_hw]}"
+puts "Std VW: #{private[:std_vw]}"
+puts "Stem snap H: #{private[:stem_snap_h]}"
+```
+
+## Converting
+
+### OTF to TTF
+
+```bash
+fontisan convert font.otf --to ttf --output font.ttf
+```
+
+### OTF to WOFF2
+
+```bash
+fontisan convert font.otf --to woff2 --output font.woff2
+```
+
+## Characteristics
+
+### Advantages
+
+- **Smaller file size** — CFF compression
+- **Cubic curves** — Fewer points needed
+- **PostScript heritage** — Print workflows
+
+### Limitations
+
+- **Limited hinting** — PostScript hints vs TrueType
+- **Variable support** — CFF2 required

data/docs/guide/formats/svg.md

@@ -0,0 +1,97 @@
+---
+title: SVG Fonts
+---
+
+# SVG Fonts
+
+SVG fonts define glyphs using SVG graphics.
+
+## Overview
+
+- **Format**: SVG document
+- **Features**: Full SVG capabilities
+- **Use Case**: Specialized applications
+
+## Structure
+
+SVG fonts are SVG documents with font definitions:
+
+```xml
+<svg>
+  <font>
+    <font-face font-family="MyFont"/>
+    <glyph unicode="A" d="M0 0 L100 0..."/>
+  </font>
+</svg>
+```
+
+## Loading
+
+```ruby
+font = Fontisan::FontLoader.load('font.svg')
+
+# Access glyphs
+font.glyphs.each do |glyph|
+  puts glyph.unicode
+  puts glyph.path_data
+end
+```
+
+## Creating
+
+SVG fonts can be created manually or with tools:
+
+```ruby
+# Export to SVG
+Fontisan::FontWriter.write(font, 'output.svg', format: :svg)
+```
+
+## Converting
+
+### SVG to TTF
+
+```bash
+fontisan convert font.svg --to ttf --output font.ttf
+```
+
+### SVG to OTF
+
+```bash
+fontisan convert font.svg --to otf --output font.otf
+```
+
+### From other formats
+
+```bash
+fontisan convert font.ttf --to svg --output font.svg
+```
+
+## Limitations
+
+- **No hinting** — SVG has no hint support
+- **Large files** — XML overhead
+- **Limited layout** — No GSUB/GPOS
+- **Variable support** — No variable fonts
+
+## SVG vs COLR/CPAL
+
+| Feature | SVG Font | COLR/CPAL |
+|---------|----------|-----------|
+| File size | Large | Small |
+| Effects | Full | Limited |
+| Browser support | Good | Good |
+| Variable fonts | No | Yes |
+| Performance | Slow | Fast |
+
+## When to Use
+
+- **SVG workflows** — Integration with SVG graphics
+- **Special effects** — Complex visual effects
+- **Legacy content** — Existing SVG fonts
+
+## Modern Alternatives
+
+For most uses, prefer:
+- **COLR/CPAL** — Color fonts
+- **WOFF2** — Web delivery
+- **OTF/TTF** — General use

data/docs/guide/formats/ttf.md

@@ -0,0 +1,105 @@
+---
+title: TrueType (TTF)
+---
+
+# TrueType (TTF)
+
+TrueType is a standard font format using quadratic Bézier curves.
+
+## Overview
+
+- **Curve Type**: Quadratic Bézier
+- **Hinting**: TrueType instructions
+- **Storage**: glyf + loca tables
+
+## Key Tables
+
+| Table | Purpose |
+|-------|---------|
+| head | Font header |
+| hhea | Horizontal header |
+| maxp | Maximum profile |
+| name | Name records |
+| cmap | Character mapping |
+| glyf | Glyph outlines |
+| loca | Glyph locations |
+| hmtx | Horizontal metrics |
+| post | PostScript names |
+| prep | Control Value Program |
+| fpgm | Font Program |
+| cvt | Control Value Table |
+
+## Loading
+
+```ruby
+font = Fontisan::FontLoader.load('font.ttf')
+
+# Access tables
+head = font.tables['head']
+glyf = font.tables['glyf']
+
+puts "Units per Em: #{head.units_per_em}"
+puts "Glyphs: #{font.tables['maxp'].num_glyphs}"
+```
+
+## Glyph Outlines
+
+```ruby
+glyph = font.glyphs[42]
+
+# Access outline
+glyph.contours.each do |contour|
+  contour.points.each do |point|
+    if point.on_curve?
+      puts "Point at (#{point.x}, #{point.y})"
+    else
+      puts "Control at (#{point.x}, #{point.y})"
+    end
+  end
+end
+```
+
+## Hinting
+
+TrueType fonts use bytecode instructions:
+
+```ruby
+prep = font.tables['prep']
+fpgm = font.tables['fpgm']
+cvt = font.tables['cvt']
+
+if prep
+  puts "Prep program: #{prep.bytecode.length} bytes"
+end
+
+if cvt
+  puts "CVT entries: #{cvt.values.length}"
+end
+```
+
+## Converting
+
+### TTF to OTF
+
+```bash
+fontisan convert font.ttf --to otf --output font.otf
+```
+
+### TTF to WOFF2
+
+```bash
+fontisan convert font.ttf --to woff2 --output font.woff2
+```
+
+## Characteristics
+
+### Advantages
+
+- **Wide support** — All platforms
+- **Excellent hinting** — TrueType instructions
+- **Variable fonts** — gvar support
+
+### Limitations
+
+- **Larger file size** — Compared to CFF
+- **Quadratic curves** — More points for complex shapes