fontisan 0.2.13 → 0.2.16

data/docs/guide/hinting/postscript.md

@@ -0,0 +1,149 @@
+---
+title: PostScript Hinting
+---
+
+# PostScript Hinting
+
+PostScript hints are declarative values stored in the CFF Private dictionary.
+
+## Hint Parameters
+
+### Blue Values
+
+Alignment zones for vertical positioning:
+
+| Parameter | Description | Max Values |
+|-----------|-------------|------------|
+| `blue_values` | Baseline and top zones | 14 (7 pairs) |
+| `other_blues` | Descender zones | 10 (5 pairs) |
+
+```ruby
+# Example blue values
+blue_values = [-20, 0, 700, 720]  # Baseline zone and cap height zone
+other_blues = [-250, -230]        # Descender zone
+```
+
+### Stem Widths
+
+Standard stem dimensions:
+
+| Parameter | Description | Max Values |
+|-----------|-------------|------------|
+| `std_hw` | Standard horizontal stem | 1 |
+| `std_vw` | Standard vertical stem | 1 |
+| `stem_snap_h` | Horizontal stem snap values | 12 |
+| `stem_snap_v` | Vertical stem snap values | 12 |
+
+```ruby
+# Example stem values
+std_hw = 80    # Standard horizontal stem width
+std_vw = 100   # Standard vertical stem width
+stem_snap_h = [80, 90, 100]  # Common H stem widths
+stem_snap_v = [100, 110, 120] # Common V stem widths
+```
+
+### Other Parameters
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `blue_scale` | Threshold for alignment zones | 0.039625 |
+| `blue_shift` | Overshoot threshold | 7 |
+| `blue_fuzz` | Blue zone expansion | 1 |
+| `force_bold` | Force bold rendering | false |
+| `language_group` | 0=Latin, 1=CJK | 0 |
+
+## Reading Hints
+
+```ruby
+font = Fontisan::FontLoader.load('font.otf')
+cff = font.tables['CFF']
+
+# Get Private DICT
+private = cff.top_dicts.first[:private]
+
+# Read hint parameters
+puts "Blue scale: #{private[:blue_scale]}"
+puts "Std H width: #{private[:std_hw]}"
+puts "Std V width: #{private[:std_vw]}"
+puts "Blue values: #{private[:blue_values]}"
+puts "Other blues: #{private[:other_blues]}"
+puts "Stem snap H: #{private[:stem_snap_h]}"
+puts "Stem snap V: #{private[:stem_snap_v]}"
+```
+
+## Validation
+
+```ruby
+validator = Fontisan::Hints::HintValidator.new
+
+hints = {
+  blue_scale: 0.039625,
+  std_hw: 80,
+  blue_values: [-20, 0, 700, 720]
+}
+
+result = validator.validate_postscript_hints(hints)
+
+if result[:valid]
+  puts "Valid PostScript hints"
+else
+  result[:errors].each { |err| puts "Error: #{err}" }
+end
+```
+
+### Validation Checks
+
+- **Value Ranges** — Validates hint parameter bounds
+- **Pair Validation** — Ensures blue zones are in pairs (even count)
+- **Array Limits** — Enforces CFF specification limits
+- **Positive Values** — Verifies stem widths are positive
+- **Language Group** — Validates value is 0 or 1
+
+## Blue Zone Examples
+
+### Latin Font
+
+```ruby
+blue_values = [
+  -20, 0,      # Baseline zone (-20 to 0)
+  470, 490,    # x-height zone (470 to 490)
+  700, 720     # Cap height zone (700 to 720)
+]
+
+other_blues = [
+  -250, -230   # Descender zone (-250 to -230)
+]
+```
+
+### CJK Font
+
+```ruby
+blue_values = [
+  -20, 0,      # Baseline
+  880, 900     # Top zone
+]
+
+other_blues = []
+
+language_group = 1  # CJK
+```
+
+## Stem Snap Values
+
+Stem snaps tell the rasterizer which widths are "standard":
+
+```ruby
+# If stems in the font are primarily 80, 90, or 100 units
+stem_snap_h = [80, 90, 100]
+
+# The rasterizer will snap stems to these values
+# when they're close enough
+```
+
+## Best Practices
+
+1. **Keep blue zones in pairs** — Each zone needs top and bottom
+2. **Use realistic values** — Stems should match actual glyph stems
+3. **Don't over-specify** — 4-5 blue zones are usually enough
+4. **Test at small sizes** — Verify hints improve rendering
+5. **Consider font size** — Adjust blue_scale for text vs display

data/docs/guide/hinting/truetype.md

@@ -0,0 +1,135 @@
+---
+title: TrueType Hinting
+---
+
+# TrueType Hinting
+
+TrueType hinting uses bytecode instructions to control glyph rendering.
+
+## Storage
+
+TrueType hints are stored in three tables:
+
+| Table | Purpose |
+|-------|---------|
+| `prep` | Control Value Program |
+| `fpgm` | Font Program |
+| `cvt` | Control Value Table |
+
+## Instructions
+
+### Stack Operations
+
+| Opcode | Name | Purpose |
+|--------|------|---------|
+| `0x40` | NPUSHB | Push n bytes onto stack |
+| `0x41` | NPUSHW | Push n words onto stack |
+| `0xB0-0xB7` | PUSHB[0-7] | Push 1-8 bytes |
+| `0xB8-0xBF` | PUSHW[0-7] | Push 1-8 words |
+
+### Control Value Instructions
+
+| Opcode | Name | Purpose |
+|--------|------|---------|
+| `0x1D` | SCVTCI | Set CVT cut-in |
+| `0x1E` | SSWCI | Set single width cut-in |
+| `0x1F` | SSW | Set single width |
+| `0x44` | WCVTP | Write CVT in pixels |
+| `0x70` | WCVTF | Write CVT in FUnits |
+
+## Reading Instructions
+
+```ruby
+font = Fontisan::FontLoader.load('font.ttf')
+
+# Get prep table
+prep = font.tables['prep']
+if prep
+  puts "Prep program: #{prep.bytecode.length} bytes"
+
+  # Parse instructions
+  parser = Fontisan::Hints::InstructionParser.new
+  instructions = parser.parse(prep.bytecode)
+
+  instructions.each do |inst|
+    puts "#{inst.opcode.to_s(16)}: #{inst.name}"
+  end
+end
+
+# Get CVT table
+cvt = font.tables['cvt']
+if cvt
+  puts "CVT entries: #{cvt.values.length}"
+  cvt.values.each_with_index do |value, i|
+    puts "  CVT[#{i}] = #{value}"
+  end
+end
+```
+
+## Validation
+
+```ruby
+validator = Fontisan::Hints::HintValidator.new
+
+# Validate prep instructions
+prep = font.tables['prep']
+result = validator.validate_truetype_instructions(prep.bytecode)
+
+if result[:valid]
+  puts "Valid instructions"
+else
+  result[:errors].each do |error|
+    puts "Error: #{error}"
+  end
+end
+```
+
+### Validation Checks
+
+- **Bytecode Structure** — Validates instruction opcodes and parameters
+- **Stack Operations** — Ensures proper stack depth management
+- **Parameter Counts** — Verifies correct number of operands
+- **Truncation Detection** — Identifies incomplete instructions
+- **Stack Neutrality** — Checks if sequences maintain stack balance
+
+## Instruction Encoding
+
+The generator automatically selects efficient encoding:
+
+### Byte Values (0-255)
+
+```
+Value 17: PUSHB[0] 17          (2 bytes)
+Values [10,20,30]: NPUSHB 3 10 20 30  (5 bytes)
+```
+
+### Word Values (256-65535)
+
+```
+Value 300: PUSHW[0] 0x01 0x2C   (3 bytes, big-endian)
+Values [300,400]: NPUSHW 2 0x01 0x2C 0x01 0x90  (7 bytes)
+```
+
+## CVT Values
+
+The Control Value Table stores frequently used values:
+
+```ruby
+cvt = font.tables['cvt']
+
+# Typical CVT layout
+# CVT[0] - Standard vertical stem width
+# CVT[1] - Standard horizontal stem width
+# CVT[2-7] - Blue zone values
+# CVT[8+] - Other common values
+
+puts "Standard V stem: #{cvt.values[0]}"
+puts "Standard H stem: #{cvt.values[1]}"
+```
+
+## Best Practices
+
+1. **Use CVT for common values** — Reduces bytecode size
+2. **Keep prep simple** — Complex programs can cause compatibility issues
+3. **Test cross-platform** — Hinting behavior varies by rasterizer
+4. **Validate before release** — Ensure instructions are well-formed

data/docs/guide/hinting.md

@@ -0,0 +1,44 @@
+# Font Hinting
+
+Fontisan provides tools for working with font hinting data.
+
+## Overview
+
+Font hinting (also known as instructing) is the process of adjusting the display of fonts to align with a pixel grid, improving legibility at small sizes.
+
+## Hinting Formats
+
+- **fpgm/cvt/prep** - TrueType instructions
+- **gasp** - Grid-fitting and scan-conversion procedure
+- **GPOS/GSUB** - OpenType positioning and substitution
+
+## Reading Hinting Data
+
+```ruby
+require 'fontisan'
+
+font = Fontisan.load('font.ttf')
+
+# Check for TrueType instructions
+if font.trueType_instructions?
+  puts "Font has TrueType hinting"
+end
+
+# Get gasp table
+if font.gasp_table
+  font.gasp_table.ranges.each do |range|
+    puts "Size #{range.range_max_ppem}: #{range.behavior}"
+  end
+end
+```
+
+## Auto-Hinting
+
+```ruby
+# Apply auto-hinting
+Fontisan.autohint('font.ttf', output: 'font-hinted.ttf')
+```
+
+## Related
+
+- [Font Conversion](/guide/conversion) - Convert fonts while preserving hinting

data/docs/guide/index.md

@@ -0,0 +1,152 @@
+---
+title: Getting Started
+---
+
+# Getting Started
+
+Fontisan is a font processing library for Ruby that provides tools for font conversion, validation, and manipulation.
+
+::: warning Font License Considerations
+Commercial fonts often come with restrictive licenses that may prohibit:
+
+- **Subsetting** — Reducing the character set
+- **Format conversion** — Converting between TTF, OTF, WOFF, etc.
+- **Variable font instancing** — Generating static instances
+- **Glyph modification** — Altering or extracting individual glyphs
+- **Redistribution** — Sharing converted or modified fonts
+
+Always check your font's End User License Agreement (EULA) before processing. Many foundries require additional licenses for web embedding, subsetting, or format conversion. **Fontisan provides the tools — you are responsible for ensuring you have the rights to use them.**
+:::
+
+## Features
+
+Fontisan provides comprehensive font processing capabilities:
+
+- **🔄 Font Conversion** — Convert between TTF, OTF, WOFF, WOFF2, Type 1, and SVG formats
+- **✅ Font Validation** — Validate fonts with 5 profiles and 56 helpers
+- **📦 Type 1 Support** — Adobe Type 1 fonts (PFB/PFA) with eexec decryption
+- **🎨 Color Fonts** — COLR/CPAL, sbix, and SVG color fonts
+- **⚡ Variable Fonts** — Instance generation, format conversion, named instances
+- **🔧 Font Hinting** — Bidirectional TrueType ↔ PostScript hint conversion
+- **📚 Collections** — TTC/OTC/dfont pack, unpack, and deduplication
+- **💎 Pure Ruby** — No Python, no C++, no C# dependencies
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'fontisan'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install fontisan
+```
+
+## Quick Start
+
+### Load a Font
+
+```ruby
+require 'fontisan'
+
+# Automatic format detection
+font = Fontisan::FontLoader.load('font.ttf')
+
+# Works with any format
+font = Fontisan::FontLoader.load('font.otf')    # OpenType
+font = Fontisan::FontLoader.load('font.woff2')  # WOFF2
+font = Fontisan::FontLoader.load('font.pfb')    # Type 1
+font = Fontisan::FontLoader.load('fonts.ttc')   # Collection
+```
+
+### Get Font Information
+
+```ruby
+# Get basic info
+info = Fontisan::Commands::InfoCommand.new(font: font).run
+puts info.family_name
+puts info.style
+puts info.version
+
+# Get table information
+tables = font.tables
+puts tables.keys
+```
+
+### Convert Fonts
+
+```ruby
+# Simple conversion
+Fontisan.convert('input.ttf', output_format: :woff2)
+
+# With custom options
+options = Fontisan::ConversionOptions.new(
+  from: :ttf,
+  to: :otf,
+  opening: { autohint: true, convert_curves: true }
+)
+Fontisan.convert('input.ttf', output_format: :otf, options: options)
+```
+
+### Validate Fonts
+
+```ruby
+# Validate with a profile
+result = Fontisan::FontValidator.validate('font.ttf', profile: :google_fonts)
+
+# Check results
+if result.passed?
+  puts "Font is valid!"
+else
+  result.errors.each do |error|
+    puts "#{error.code}: #{error.message}"
+  end
+end
+```
+
+## CLI Usage
+
+Fontisan includes a comprehensive CLI:
+
+```bash
+# Get font information
+fontisan info font.ttf
+
+# List fonts in a collection
+fontisan ls fonts.ttc
+
+# Convert fonts
+fontisan convert input.ttf --to otf --output output.otf
+
+# Validate fonts
+fontisan validate font.ttf --profile google_fonts
+
+# Extract fonts from collection
+fontisan unpack fonts.ttc --output-dir ./extracted
+
+# Pack fonts into collection
+fontisan pack font1.ttf font2.ttf --output fonts.ttc
+
+# Export to TTX
+fontisan export font.ttf --format ttx
+
+# Subset fonts
+fontisan subset font.ttf --chars "ABC123"
+```
+
+## Next Steps
+
+- [Installation Details](/guide/installation) — Detailed installation options
+- [Quick Start Guide](/guide/quick-start) — Common workflows
+- [CLI Reference](/guide/cli/) — Command-line documentation
+- [Font Formats](/guide/formats/) — Supported format details
+- [Conversion Guide](/guide/conversion/) — Conversion options and best practices

data/docs/guide/installation.md

@@ -0,0 +1,116 @@
+---
+title: Installation
+---
+
+# Installation
+
+## Requirements
+
+- Ruby 3.0 or higher
+- No external dependencies (pure Ruby)
+
+## Installing the Gem
+
+### With Bundler
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'fontisan'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+### Manual Installation
+
+Install it yourself as:
+
+```bash
+gem install fontisan
+```
+
+## Verifying Installation
+
+```bash
+# Check if CLI is available
+fontisan --version
+
+# Get help
+fontisan --help
+```
+
+## Installing from Source
+
+For development or to use the latest features:
+
+```bash
+git clone https://github.com/fontist/fontisan.git
+cd fontisan
+bundle install
+bundle exec rake install
+```
+
+## Dependencies
+
+Fontisan is **100% pure Ruby** with no external dependencies:
+
+- No Python required
+- No C++ compilation needed
+- No native extensions
+- Works on Linux, macOS, Windows, and BSD
+
+### Optional Dependencies
+
+For development:
+
+```bash
+# Install development dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run linter
+bundle exec rubocop
+```
+
+## Troubleshooting
+
+### Ruby Version
+
+Fontisan requires Ruby 3.0 or higher. Check your version:
+
+```bash
+ruby --version
+```
+
+### Permission Issues
+
+If you encounter permission errors, try:
+
+```bash
+# Install to user directory
+gem install fontisan --user-install
+
+# Or use sudo (not recommended)
+sudo gem install fontisan
+```
+
+### Bundler Issues
+
+If Bundler has issues:
+
+```bash
+# Update Bundler
+gem update bundler
+
+# Clear cache
+bundle clean --force
+
+# Reinstall
+bundle install --redownload
+```