fontisan 0.2.13 → 0.2.16

data/docs/guide/variable-fonts/instances.md

@@ -0,0 +1,187 @@
+---
+title: Instance Generation
+---
+
+# Instance Generation
+
+Generate static font instances from variable fonts at specific variation coordinates.
+
+## CLI Usage
+
+### Basic Instance Generation
+
+```bash
+# Generate at specific weight
+fontisan instance variable.ttf --wght 700 --output bold.ttf
+
+# Generate at specific weight and width
+fontisan instance variable.ttf --wght 700 --wdth 75 --output condensed-bold.ttf
+
+# Generate with all axes
+fontisan instance variable.ttf --wght 600 --wdth 90 --slnt -12 --output custom.ttf
+```
+
+### Using Named Instances
+
+```bash
+# List available instances
+fontisan instance variable.ttf --list-instances
+
+# Generate using instance index
+fontisan instance variable.ttf --named-instance 0 --output thin.ttf
+
+# Generate using instance name
+fontisan instance variable.ttf --named-instance "Bold" --output bold.ttf
+```
+
+### Output Format
+
+```bash
+# Generate as TrueType (default)
+fontisan instance variable.ttf --wght 700 --output bold.ttf
+
+# Generate as OpenType/CFF
+fontisan instance variable.ttf --wght 700 --to otf --output bold.otf
+
+# Generate as WOFF2
+fontisan instance.ttf --wght 700 --to woff2 --output bold.woff2
+```
+
+## Ruby API
+
+### Basic Generation
+
+```ruby
+require 'fontisan'
+
+# Load variable font
+font = Fontisan::FontLoader.load('variable.ttf')
+
+# Generate instance at specific coordinates
+writer = Fontisan::Variation::InstanceWriter.new(font)
+instance_font = writer.generate_instance(wght: 700)
+
+# Write to file
+Fontisan::FontWriter.write(
+  instance_font,
+  'bold.ttf'
+)
+```
+
+### Multiple Axes
+
+```ruby
+# Generate instance with multiple axis values
+instance_font = writer.generate_instance(
+  wght: 700,
+  wdth: 75,
+  slnt: -8
+)
+```
+
+### Using Named Instances
+
+```ruby
+# Get named instance information
+fvar = font.tables['fvar']
+instance = fvar.instances[0]
+
+# Extract coordinates from named instance
+coordinates = {}
+fvar.axes.each_with_index do |axis, i|
+  coordinates[axis.tag] = instance.coordinates[i]
+end
+
+# Generate instance
+instance_font = writer.generate_instance(coordinates)
+```
+
+## Batch Generation
+
+### Generate All Named Instances
+
+```ruby
+font = Fontisan::FontLoader.load('variable.ttf')
+fvar = font.tables['fvar']
+writer = Fontisan::Variation::InstanceWriter.new(font)
+
+fvar.instances.each do |instance|
+  # Build coordinates hash
+  coordinates = {}
+  fvar.axes.each_with_index do |axis, i|
+    coordinates[axis.tag] = instance.coordinates[i]
+  end
+
+  # Generate instance
+  instance_font = writer.generate_instance(coordinates)
+
+  # Write with instance name
+  filename = instance.name.downcase.gsub(/\s+/, '-') + '.ttf'
+  Fontisan::FontWriter.write(instance_font, filename)
+end
+```
+
+### Generate Weight Range
+
+```ruby
+# Generate instances for common weights
+weights = {
+  'thin' => 100,
+  'light' => 300,
+  'regular' => 400,
+  'medium' => 500,
+  'semibold' => 600,
+  'bold' => 700,
+  'black' => 900
+}
+
+weights.each do |name, wght|
+  instance_font = writer.generate_instance(wght: wght)
+  Fontisan::FontWriter.write(instance_font, "#{name}.ttf")
+end
+```
+
+## Instance Quality
+
+### Coordinate Validation
+
+Coordinates must be within axis ranges:
+
+```ruby
+fvar = font.tables['fvar']
+
+fvar.axes.each do |axis|
+  min = axis.min_value
+  max = axis.max_value
+
+  if value < min || value > max
+    raise "Value #{value} out of range for #{axis.tag}"
+  end
+end
+```
+
+### Default Values
+
+When an axis is not specified, the default value is used:
+
+```ruby
+# If wght is not specified, uses default from fvar
+instance_font = writer.generate_instance(wdth: 75)
+```
+
+## Performance
+
+### Caching
+
+Fontisan caches intermediate computations for faster instance generation:
+
+```ruby
+# Create writer once
+writer = Fontisan::Variation::InstanceWriter.new(font)
+
+# Generate multiple instances efficiently
+(100..900).step(100).each do |wght|
+  instance_font = writer.generate_instance(wght: wght)
+  # ...
+end
+```

data/docs/guide/variable-fonts/named-instances.md

@@ -0,0 +1,194 @@
+---
+title: Named Instances
+---
+
+# Named Instances
+
+Work with named instances in variable fonts.
+
+## Overview
+
+Named instances are predefined points in the design space with specific names. They provide:
+- User-friendly names for common variations
+- Consistent styling across applications
+- Easy access to frequently used configurations
+
+## Listing Named Instances
+
+### CLI
+
+```bash
+fontisan instance variable.ttf --list-instances
+
+# Example output:
+# Named Instances: 6
+#   0: Thin (wght=100)
+#   1: Light (wght=300)
+#   2: Regular (wght=400)
+#   3: Medium (wght=500)
+#   4: Bold (wght=700)
+#   5: Black (wght=900)
+```
+
+### API
+
+```ruby
+font = Fontisan::FontLoader.load('variable.ttf')
+fvar = font.tables['fvar']
+
+fvar.instances.each_with_index do |instance, index|
+  puts "#{index}: #{instance.name}"
+  instance.coordinates.each do |tag, value|
+    puts "  #{tag} = #{value}"
+  end
+end
+```
+
+## Instance Properties
+
+| Property | Description |
+|----------|-------------|
+| `name` | Human-readable instance name |
+| `coordinates` | Hash of axis tag → value |
+
+## Generating Named Instances
+
+### By Index
+
+```bash
+# Generate first named instance
+fontisan instance variable.ttf --named-instance 0 --output thin.ttf
+
+# Generate third named instance
+fontisan instance variable.ttf --named-instance 2 --output regular.ttf
+```
+
+### By Name
+
+```bash
+# Generate by name
+fontisan instance variable.ttf --named-instance "Bold" --output bold.ttf
+```
+
+### API
+
+```ruby
+font = Fontisan::FontLoader.load('variable.ttf')
+fvar = font.tables['fvar']
+writer = Fontisan::Variation::InstanceWriter.new(font)
+
+# Find instance by name
+bold_instance = fvar.instances.find { |i| i.name == "Bold" }
+
+if bold_instance
+  # Build coordinates hash
+  coordinates = {}
+  fvar.axes.each_with_index do |axis, i|
+    coordinates[axis.tag] = bold_instance.coordinates[i]
+  end
+
+  # Generate instance
+  bold_font = writer.generate_instance(coordinates)
+  Fontisan::FontWriter.write(bold_font, 'bold.ttf')
+end
+```
+
+## Generating All Named Instances
+
+```ruby
+font = Fontisan::FontLoader.load('variable.ttf')
+fvar = font.tables['fvar']
+writer = Fontisan::Variation::InstanceWriter.new(font)
+
+fvar.instances.each do |instance|
+  # Build coordinates
+  coordinates = {}
+  fvar.axes.each_with_index do |axis, i|
+    coordinates[axis.tag] = instance.coordinates[i]
+  end
+
+  # Generate instance
+  instance_font = writer.generate_instance(coordinates)
+
+  # Create safe filename
+  filename = instance.name.downcase.gsub(/[^a-z0-9]+, '-') + '.ttf'
+
+  Fontisan::FontWriter.write(instance_font, filename)
+  puts "Generated: #{filename}"
+end
+```
+
+## Instance Names
+
+Instance names follow conventions:
+
+### Weight-Based
+
+- Thin
+- Extra Light
+- Light
+- Regular
+- Medium
+- Semi Bold
+- Bold
+- Extra Bold
+- Black
+
+### Width-Based
+
+- Ultra Condensed
+- Extra Condensed
+- Condensed
+- Semi Condensed
+- Normal
+- Semi Expanded
+- Expanded
+- Extra Expanded
+- Ultra Expanded
+
+### Combinations
+
+- Condensed Bold
+- Expanded Light
+- Semi Condensed Medium
+
+## STAT Table
+
+The STAT table provides additional instance information:
+
+```ruby
+stat = font.tables['STAT']
+
+if stat
+  stat.axis_values.each do |axis_value|
+    puts "#{axis_value.name}"
+    puts "  Axis: #{axis_value.axis_tag}"
+    puts "  Value: #{axis_value.value}"
+    puts "  Linked: #{axis_value.linked_value}" if axis_value.linked_value
+  end
+end
+```
+
+## Instance Validation
+
+Validate instances before generation:
+
+```ruby
+fvar = font.tables['fvar']
+
+fvar.instances.each do |instance|
+  valid = true
+
+  fvar.axes.each_with_index do |axis, i|
+    value = instance.coordinates[i]
+    if value < axis.min_value || value > axis.max_value
+      puts "Warning: #{instance.name} has #{axis.tag}=#{value} out of range"
+      valid = false
+    end
+  end
+
+  if valid
+    puts "#{instance.name}: Valid"
+  end
+end
+```

data/docs/guide/variable-fonts/static.md

@@ -0,0 +1,168 @@
+---
+title: Static Fonts
+---
+
+# Static Fonts
+
+Convert variable fonts to static fonts.
+
+## Overview
+
+Static fonts are traditional fonts with fixed designs. Converting a variable font to static creates a snapshot at specific coordinates.
+
+## When to Use Static Fonts
+
+- **Legacy Compatibility** — Older systems that don't support variable fonts
+- **Performance** — Smaller file size for single weights
+- **Simplicity** — No need for variation handling
+- **Distribution** — Some platforms don't support variable fonts
+
+## Creating Static Fonts
+
+### At Default Coordinates
+
+```bash
+# Create static font at default variation
+fontisan convert variable.ttf --to ttf --output static.ttf
+```
+
+### At Specific Coordinates
+
+```bash
+# Create static bold font
+fontisan instance variable.ttf --wght 700 --output bold-static.ttf
+```
+
+### Remove Variation Data
+
+```bash
+# Explicitly remove variation tables
+fontisan convert variable.ttf --to ttf --no-preserve-variation --output static.ttf
+```
+
+## API Usage
+
+### Default Coordinates
+
+```ruby
+font = Fontisan::FontLoader.load('variable.ttf')
+
+# Generate at default (empty hash = all default values)
+writer = Fontisan::Variation::InstanceWriter.new(font)
+static_font = writer.generate_instance({})
+
+Fontisan::FontWriter.write(static_font, 'static.ttf')
+```
+
+### Specific Coordinates
+
+```ruby
+# Generate static at specific coordinates
+static_bold = writer.generate_instance(wght: 700)
+Fontisan::FontWriter.write(static_bold, 'bold-static.ttf')
+
+# Generate static with multiple axes
+static_condensed_bold = writer.generate_instance(wght: 700, wdth: 75)
+Fontisan::FontWriter.write(static_condensed_bold, 'condensed-bold.ttf')
+```
+
+## What Gets Removed
+
+When creating a static font, these tables are removed:
+
+| Table | Status |
+|-------|--------|
+| fvar | Removed |
+| gvar | Removed |
+| CFF2 | Converted to CFF |
+| avar | Removed |
+| HVAR | Applied to hmtx, removed |
+| VVAR | Applied to vmtx, removed |
+| MVAR | Applied to tables, removed |
+
+## What Gets Generated
+
+The static font contains:
+
+| Table | Source |
+|-------|--------|
+| glyf | Interpolated from gvar |
+| CFF | Interpolated from CFF2 |
+| hmtx | Interpolated from HVAR |
+| vmtx | Interpolated from VVAR |
+| Other tables | Copied unchanged |
+
+## Batch Generation
+
+### Generate Weight Range
+
+```ruby
+font = Fontisan::FontLoader.load('variable.ttf')
+writer = Fontisan::Variation::InstanceWriter.new(font)
+
+weights = {
+  'thin' => 100,
+  'light' => 300,
+  'regular' => 400,
+  'medium' => 500,
+  'semibold' => 600,
+  'bold' => 700,
+  'extrabold' => 800,
+  'black' => 900
+}
+
+weights.each do |name, wght|
+  static_font = writer.generate_instance(wght: wght)
+
+  # Also convert to WOFF2 for web
+  options = Fontisan::ConversionOptions.from_preset(:web_optimized)
+  Fontisan::FontWriter.write(static_font, "#{name}.woff2", options: options)
+end
+```
+
+### Generate 2D Grid
+
+```ruby
+# Generate grid of weight × width combinations
+weights = [100, 400, 700]
+widths = [75, 100, 125]
+
+weights.each do |wght|
+  widths.each do |wdth|
+    static_font = writer.generate_instance(wght: wght, wdth: wdth)
+    filename = "wght-#{wght}-wdth-#{wdth}.ttf"
+    Fontisan::FontWriter.write(static_font, filename)
+  end
+end
+```
+
+## File Size Comparison
+
+| Font Type | Typical Size |
+|-----------|--------------|
+| Variable font | 100-300 KB |
+| Static (single) | 20-50 KB |
+| Static (9 weights) | 180-450 KB |
+
+Variable fonts are smaller when you need multiple variations. Static fonts are smaller for single variations.
+
+## Quality Considerations
+
+### Interpolation Accuracy
+
+Static fonts are mathematically precise interpolations:
+
+```ruby
+# The interpolated outlines match the variable font exactly
+# at the specified coordinates
+```
+
+### Hinting
+
+- TrueType hints are interpolated along with outlines
+- Some hint instructions may not apply to new coordinates
+- Consider re-hinting after generation
+
+### Subpixel Rendering
+
+Static fonts may render differently than variable fonts at the same coordinates due to hinting differences.

data/docs/guide/variable.md

@@ -0,0 +1,58 @@
+# Variable Fonts
+
+Fontisan provides tools for working with OpenType variable fonts.
+
+## Overview
+
+Variable fonts (OpenType Font Variations) allow a single font file to contain multiple variations along design axes (weight, width, slant, etc.).
+
+## Reading Variable Fonts
+
+```ruby
+require 'fontisan'
+
+# Load a variable font
+font = Fontisan.load('variable-font.ttf')
+
+# Check if font is variable
+if font.variable?
+  puts "This is a variable font"
+end
+```
+
+## Font Axes
+
+```ruby
+# Get available axes
+font.axes.each do |axis|
+  puts "#{axis.tag}: #{axis.name}"
+  puts "  Range: #{axis.min} - #{axis.max}"
+  puts "  Default: #{axis.default}"
+end
+```
+
+## Named Instances
+
+```ruby
+# Get named instances
+font.named_instances.each do |instance|
+  puts "#{instance.name}:"
+  instance.coordinates.each do |tag, value|
+    puts "  #{tag}: #{value}"
+  end
+end
+```
+
+## Working with Variations
+
+```ruby
+# Create a variation
+variation = font.variation('wght' => 700, 'wdth' => 100)
+
+# Export as static font
+variation.export('font-bold.ttf')
+```
+
+## Related
+
+- [Color Fonts](/guide/color) - Color font support

data/docs/guide/woff.md

@@ -0,0 +1,59 @@
+# WOFF/WOFF2 Formats
+
+Fontisan supports the Web Open Font Format (WOFF and WOFF2).
+
+## Overview
+
+WOFF and WOFF2 are web font formats optimized for use on websites:
+
+- **WOFF** - Compressed version of TrueType/OpenType with metadata support
+- **WOFF2** - Improved compression using Brotli algorithm (typically 30% smaller than WOFF)
+
+## Converting to WOFF
+
+```ruby
+require 'fontisan'
+
+# Convert to WOFF
+Fontisan.convert('font.ttf', output_format: :woff)
+
+# Convert to WOFF2 (recommended for web)
+Fontisan.convert('font.ttf', output_format: :woff2)
+```
+
+## Metadata
+
+WOFF files can contain extended metadata:
+
+```ruby
+# Add metadata when converting
+Fontisan.convert('font.ttf',
+  output_format: :woff2,
+  metadata: {
+    unique_id: 'my-font-1.0',
+    license: 'OFL',
+    license_url: 'https://scripts.sil.org/OFL',
+    description: 'My custom font'
+  }
+)
+```
+
+## Extracting from WOFF
+
+```ruby
+# Extract original font from WOFF
+Fontisan.convert('font.woff', output_format: :ttf)
+Fontisan.convert('font.woff2', output_format: :otf)
+```
+
+## Compression Comparison
+
+| Format | Size (relative) |
+|--------|----------------|
+| TTF/OTF | 100% |
+| WOFF | ~70% |
+| WOFF2 | ~50% |
+
+## Related
+
+- [Font Conversion](/guide/conversion) - General conversion guide