fontisan 0.2.14 → 0.2.17

data/docs/api/conversion-options.md

@@ -0,0 +1,141 @@
+---
+title: ConversionOptions
+---
+
+# ConversionOptions
+
+Type-safe conversion configuration.
+
+## Overview
+
+`Fontisan::ConversionOptions` provides a type-safe way to configure font conversions.
+
+## Class Methods
+
+### recommended(from:, to:)
+
+Get recommended options for a conversion type.
+
+```ruby
+options = Fontisan::ConversionOptions.recommended(from: :ttf, to: :otf)
+# => #<Fontisan::ConversionOptions ...>
+
+# Access settings
+options.opening   # => { convert_curves: true, ... }
+options.generating # => { hinting_mode: "auto", ... }
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| from | Symbol | Source format |
+| to | Symbol | Target format |
+
+### from_preset(name)
+
+Load options from a named preset.
+
+```ruby
+# Web optimization preset
+options = Fontisan::ConversionOptions.from_preset(:web_optimized)
+
+# Type 1 to modern
+options = Fontisan::ConversionOptions.from_preset(:type1_to_modern)
+```
+
+**Available Presets:**
+
+| Preset | From | To |
+|--------|------|-----|
+| `type1_to_modern` | Type 1 | OTF |
+| `modern_to_type1` | OTF | Type 1 |
+| `web_optimized` | OTF | WOFF2 |
+| `archive_to_modern` | TTC | OTF |
+
+### new(**kwargs)
+
+Create custom options.
+
+```ruby
+options = Fontisan::ConversionOptions.new(
+  from: :ttf,
+  to: :otf,
+  opening: {
+    convert_curves: true,
+    autohint: true
+  },
+  generating: {
+    hinting_mode: 'auto',
+    optimize_tables: true
+  }
+)
+```
+
+## Instance Attributes
+
+### opening
+
+Opening options control source font processing.
+
+| Option | Type | Default |
+|--------|------|---------|
+| `decompose_composites` | Boolean | false |
+| `convert_curves` | Boolean | true |
+| `scale_to_1000` | Boolean | false |
+| `scale_from_1000` | Boolean | false |
+| `autohint` | Boolean | false |
+| `generate_unicode` | Boolean | false |
+| `store_custom_tables` | Boolean | true |
+| `store_native_hinting` | Boolean | false |
+| `interpret_ot` | Boolean | false |
+| `read_all_records` | Boolean | false |
+| `preserve_encoding` | String | nil |
+
+### generating
+
+Generating options control output font writing.
+
+| Option | Type | Default |
+|--------|------|---------|
+| `write_pfm` | Boolean | false |
+| `write_afm` | Boolean | false |
+| `write_inf` | Boolean | false |
+| `select_encoding_automatically` | Boolean | false |
+| `hinting_mode` | String | 'preserve' |
+| `decompose_on_output` | Boolean | false |
+| `write_custom_tables` | Boolean | true |
+| `optimize_tables` | Boolean | false |
+| `compression` | String | nil |
+| `transform_tables` | Boolean | false |
+| `preserve_metadata` | Boolean | true |
+
+## Examples
+
+### Basic Conversion
+
+```ruby
+options = Fontisan::ConversionOptions.recommended(from: :ttf, to: :otf)
+converter = Fontisan::Converters::OutlineConverter.new
+result = converter.convert(font, options: options)
+```
+
+### Web Optimization
+
+```ruby
+options = Fontisan::ConversionOptions.from_preset(:web_optimized)
+Fontisan::FontWriter.write(font, 'output.woff2', options: options)
+```
+
+### Custom Options
+
+```ruby
+options = Fontisan::ConversionOptions.new(
+  opening: { autohint: true },
+  generating: {
+    hinting_mode: 'auto',
+    optimize_tables: true,
+    compression: 'brotli'
+  }
+)
+```

data/docs/api/converters/curve-converter.md

@@ -0,0 +1,34 @@
+---
+title: CurveConverter
+---
+
+# CurveConverter
+
+Convert between quadratic and cubic curves.
+
+## Overview
+
+`Fontisan::Converters::CurveConverter` handles Bézier curve conversion.
+
+## Methods
+
+### quadratic_to_cubic(points)
+
+Convert quadratic points to cubic.
+
+```ruby
+converter = Fontisan::Converters::CurveConverter.new
+cubic = converter.quadratic_to_cubic(quadratic_points)
+```
+
+### cubic_to_quadratic(points, tolerance: 0.5)
+
+Convert cubic points to quadratic.
+
+```ruby
+quadratic = converter.cubic_to_quadratic(cubic_points, tolerance: 0.5)
+```
+
+## See Also
+
+- [OutlineConverter](/api/converters/outline-converter)

data/docs/api/converters/hint-converter.md

@@ -0,0 +1,34 @@
+---
+title: HintConverter
+---
+
+# HintConverter
+
+Convert hints between TrueType and PostScript formats.
+
+## Overview
+
+`Fontisan::Converters::HintConverter` handles bidirectional hint conversion.
+
+## Methods
+
+### truetype_to_postscript(font)
+
+Convert TrueType instructions to PostScript hints.
+
+```ruby
+converter = Fontisan::Converters::HintConverter.new
+ps_hints = converter.truetype_to_postscript(font)
+```
+
+### postscript_to_truetype(font)
+
+Convert PostScript hints to TrueType instructions.
+
+```ruby
+ttf_tables = converter.postscript_to_truetype(font)
+```
+
+## See Also
+
+- [Font Hinting Guide](/guide/hinting/)

data/docs/api/converters/outline-converter.md

@@ -0,0 +1,27 @@
+---
+title: OutlineConverter
+---
+
+# OutlineConverter
+
+Convert font outlines between formats.
+
+## Overview
+
+`Fontisan::Converters::OutlineConverter` handles TTF ↔ OTF conversion.
+
+## Methods
+
+### convert(font, options: nil)
+
+Convert a font to a different format.
+
+```ruby
+converter = Fontisan::Converters::OutlineConverter.new
+options = Fontisan::ConversionOptions.recommended(from: :ttf, to: :otf)
+result = converter.convert(font, options: options)
+```
+
+## See Also
+
+- [ConversionOptions](/api/conversion-options)

data/docs/api/font-loader.md

@@ -0,0 +1,117 @@
+---
+title: FontLoader
+---
+
+# FontLoader
+
+Unified font loading with automatic format detection.
+
+## Overview
+
+`Fontisan::FontLoader` provides a unified interface for loading fonts in any supported format.
+
+## Class Methods
+
+### load(source)
+
+Load a font from file path or IO.
+
+```ruby
+# From file path
+font = Fontisan::FontLoader.load('font.ttf')
+font = Fontisan::FontLoader.load('font.otf')
+font = Fontisan::FontLoader.load('font.pfb')
+font = Fontisan::FontLoader.load('font.woff2')
+
+# From IO
+font = Fontisan::FontLoader.load(File.open('font.ttf'))
+
+# From string
+font = Fontisan::FontLoader.load(File.read('font.ttf', mode: 'rb'))
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| source | String, IO | File path, IO object, or binary data |
+
+**Returns:** SfntFont, Type1Font, or Collection
+
+**Raises:** Fontisan::FormatError if format is unsupported
+
+### detect_format(path)
+
+Detect a font's on-disk format from its content (magic bytes). The file
+extension is ignored — a `.ttc` that actually contains a single OpenType-CFF
+font is reported as `:otf`.
+
+```ruby
+format = Fontisan::FontLoader.detect_format('font.ttf')
+# => :ttf
+
+format = Fontisan::FontLoader.detect_format('font.otf')
+# => :otf
+
+format = Fontisan::FontLoader.detect_format('font.pfb')
+# => :pfb
+
+format = Fontisan::FontLoader.detect_format('font.pfa')
+# => :pfa
+```
+
+**Returns:** Symbol (`:ttf`, `:otf`, `:ttc`, `:otc`, `:woff`, `:woff2`,
+`:dfont`, `:pfa`, `:pfb`) or `nil` if the format is not recognised.
+
+## Supported Formats
+
+| Symbol  | Detection   | Notes                          |
+|---------|-------------|--------------------------------|
+| `:ttf`   | Magic bytes | TrueType                       |
+| `:otf`   | Magic bytes | OpenType / CFF                 |
+| `:ttc`   | Magic bytes | TrueType Collection            |
+| `:otc`   | Magic bytes | OpenType Collection            |
+| `:woff`  | Magic bytes | Web Open Font Format           |
+| `:woff2` | Magic bytes | Web Open Font Format 2         |
+| `:pfb`   | Marker byte | Adobe Type 1 Binary            |
+| `:pfa`   | Text header | Adobe Type 1 ASCII             |
+| `:dfont` | Magic bytes | Apple Data-Fork resource fork  |
+
+## Examples
+
+### Load with Error Handling
+
+```ruby
+begin
+  font = Fontisan::FontLoader.load(path)
+  puts "Loaded: #{font.family_name}"
+rescue Fontisan::FormatError => e
+  puts "Unsupported format: #{e.message}"
+rescue Errno::ENOENT => e
+  puts "File not found: #{path}"
+end
+```
+
+### Batch Loading
+
+```ruby
+fonts = Dir.glob('fonts/*.ttf').map do |path|
+  Fontisan::FontLoader.load(path)
+end
+
+puts "Loaded #{fonts.length} fonts"
+```
+
+### Detect and Load
+
+```ruby
+path = 'unknown.dat'
+
+format = Fontisan::FontLoader.detect_format(path)
+if format
+  puts "Detected format: #{format}"
+  font = Fontisan::FontLoader.load(path)
+else
+  puts "Unknown format"
+end
+```

data/docs/api/font-writer.md

@@ -0,0 +1,103 @@
+---
+title: FontWriter
+---
+
+# FontWriter
+
+Write fonts to various formats.
+
+## Overview
+
+`Fontisan::FontWriter` handles saving fonts to files in various formats.
+
+## Class Methods
+
+### write(font, path, options: {})
+
+Write a font to a file.
+
+```ruby
+font = Fontisan::FontLoader.load('input.ttf')
+
+# Write as TTF
+Fontisan::FontWriter.write(font, 'output.ttf')
+
+# Write as OTF
+Fontisan::FontWriter.write(font, 'output.otf')
+
+# Write as WOFF2
+Fontisan::FontWriter.write(font, 'output.woff2')
+
+# With options
+options = Fontisan::ConversionOptions.new(
+  generating: { optimize_tables: true }
+)
+Fontisan::FontWriter.write(font, 'output.ttf', options: options)
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| font | SfntFont, Type1Font | Font object |
+| path | String | Output file path |
+| options | ConversionOptions | Optional settings |
+
+**Returns:** Boolean
+
+### write_to_file(data, path, sfnt_version: nil)
+
+Write raw font data to a file.
+
+```ruby
+# Write raw table data
+Fontisan::FontWriter.write_to_file(
+  font.table_data,
+  'output.ttf',
+  sfnt_version: 0x00010000
+)
+```
+
+## Output Formats
+
+| Format | Extension | Notes |
+|--------|-----------|-------|
+| TTF | .ttf | TrueType |
+| OTF | .otf | OpenType/CFF |
+| WOFF | .woff | Web Open Font Format |
+| WOFF2 | .woff2 | Web Open Font Format 2 |
+| PFB | .pfb | Adobe Type 1 |
+| SVG | .svg | SVG Font |
+
+## Examples
+
+### Convert and Write
+
+```ruby
+# Load TTF
+font = Fontisan::FontLoader.load('input.ttf')
+
+# Convert to OTF
+options = Fontisan::ConversionOptions.recommended(from: :ttf, to: :otf)
+converter = Fontisan::Converters::OutlineConverter.new
+otf_tables = converter.convert(font, options: options)
+
+# Write OTF
+Fontisan::FontWriter.write(otf_tables, 'output.otf')
+```
+
+### Batch Writing
+
+```ruby
+fonts.each_with_index do |font, i|
+  Fontisan::FontWriter.write(font, "output-#{i}.ttf")
+end
+```
+
+### Web Optimization
+
+```ruby
+font = Fontisan::FontLoader.load('input.otf')
+options = Fontisan::ConversionOptions.from_preset(:web_optimized)
+Fontisan::FontWriter.write(font, 'output.woff2', options: options)
+```

data/docs/api/index.md

@@ -0,0 +1,79 @@
+---
+title: API Reference
+---
+
+# API Reference
+
+This section provides detailed API documentation for Fontisan's core classes, converters, validators, and models.
+
+## Core Classes
+
+- [FontLoader](/api/font-loader) — Unified font loading with automatic format detection
+- [FontWriter](/api/font-writer) — Write fonts to various formats
+- [ConversionOptions](/api/conversion-options) — Type-safe conversion configuration
+- [SfntFont](/api/sfnt-font) — Base class for TrueType/OpenType fonts
+- [Type1Font](/api/type1-font) — Adobe Type 1 font handler
+
+## Converters
+
+- [OutlineConverter](/api/converters/outline-converter) — TTF ↔ OTF outline conversion
+- [CurveConverter](/api/converters/curve-converter) — Quadratic ↔ Cubic curve conversion
+- [HintConverter](/api/converters/hint-converter) — TrueType ↔ PostScript hint conversion
+
+## Validators
+
+- [FontValidator](/api/validators/font-validator) — Main validation entry point
+- [ValidationProfile](/api/validators/profile) — Validation profile definitions
+- [ValidationHelper](/api/validators/helper) — Individual validation helpers
+
+## Models
+
+- [Glyph](/api/models/glyph) — Font glyph representation
+- [GlyphAccessor](/api/models/glyph-accessor) — Unified glyph access with caching
+- [TableAnalyzer](/api/models/table-analyzer) — Font table analysis
+
+## Using the API
+
+### Loading Fonts
+
+```ruby
+require 'fontisan'
+
+# Automatic format detection
+font = Fontisan::FontLoader.load('font.ttf')
+font = Fontisan::FontLoader.load('font.otf')
+font = Fontisan::FontLoader.load('font.pfb')
+
+# Load from IO
+font = Fontisan::FontLoader.load(io)
+```
+
+### Converting Fonts
+
+```ruby
+# Get recommended options
+options = Fontisan::ConversionOptions.recommended(from: :ttf, to: :otf)
+
+# Convert with options
+converter = Fontisan::Converters::OutlineConverter.new
+tables = converter.convert(font, options: options)
+
+# Write the result
+Fontisan::FontWriter.write(font, 'output.otf')
+```
+
+### Validating 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
+```

data/docs/api/models/glyph-accessor.md

@@ -0,0 +1,43 @@
+---
+title: GlyphAccessor
+---
+
+# GlyphAccessor
+
+Unified glyph access with caching.
+
+## Overview
+
+`Fontisan::GlyphAccessor` provides efficient glyph access.
+
+## Methods
+
+### at(id) / get(id)
+
+Access glyph by ID.
+
+```ruby
+glyph = font.glyphs[42]
+```
+
+### each
+
+Iterate over all glyphs.
+
+```ruby
+font.glyphs.each do |glyph|
+  puts glyph.name
+end
+```
+
+### count
+
+Get glyph count.
+
+```ruby
+count = font.glyphs.count
+```
+
+## See Also
+
+- [Glyph](/api/models/glyph)

data/docs/api/models/glyph.md

@@ -0,0 +1,40 @@
+---
+title: Glyph
+---
+
+# Glyph
+
+Font glyph representation.
+
+## Overview
+
+`Fontisan::Glyph` represents a single glyph.
+
+## Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `id` | Integer | Glyph ID |
+| `name` | String | Glyph name |
+| `unicode` | Integer | Unicode codepoint |
+| `bounds` | Hash | Bounding box |
+| `contours` | Array | Outline contours |
+
+## Methods
+
+### outline
+
+Get glyph outline.
+
+```ruby
+outline = glyph.outline
+outline.contours.each do |contour|
+  contour.points.each do |point|
+    puts "(#{point.x}, #{point.y})"
+  end
+end
+```
+
+## See Also
+
+- [GlyphAccessor](/api/models/glyph-accessor)

data/docs/api/models/table-analyzer.md

@@ -0,0 +1,35 @@
+---
+title: TableAnalyzer
+---
+
+# TableAnalyzer
+
+Font table analysis.
+
+## Overview
+
+`Fontisan::TableAnalyzer` analyzes font tables.
+
+## Methods
+
+### analyze(fonts, parallel: false)
+
+Analyze fonts for table sharing.
+
+```ruby
+analyzer = Fontisan::TableAnalyzer.new(fonts, parallel: true)
+stats = analyzer.analyze
+puts "Shared tables: #{stats.shared_count}"
+```
+
+### checksum(table)
+
+Calculate table checksum.
+
+```ruby
+checksum = analyzer.checksum(font.tables['head'])
+```
+
+## See Also
+
+- [Collections Guide](/guide/formats/collections)

data/docs/api/sfnt-font.md

@@ -0,0 +1,53 @@
+---
+title: SfntFont
+---
+
+# SfntFont
+
+Base class for TrueType and OpenType fonts.
+
+## Overview
+
+`Fontisan::SfntFont` is the base class for sfnt-based fonts (TTF, OTF, WOFF, WOFF2).
+
+## Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `tables` | Hash | Font tables by tag |
+| `glyphs` | GlyphAccessor | Glyph access object |
+| `family_name` | String | Font family name |
+| `style` | String | Font style |
+| `version` | String | Font version |
+
+## Methods
+
+### table(tag)
+
+Access a specific table.
+
+```ruby
+head = font.table('head')
+name = font.table('name')
+```
+
+### glyph_name(id)
+
+Get glyph name by ID.
+
+```ruby
+name = font.glyph_name(42)
+```
+
+### glyph_count
+
+Get total glyph count.
+
+```ruby
+count = font.glyph_count
+```
+
+## See Also
+
+- [FontLoader](/api/font-loader)
+- [Type1Font](/api/type1-font)