fontisan 0.2.13 → 0.2.16

data/docs/guide/comparisons/lcdf-typetools.md

@@ -0,0 +1,205 @@
+---
+title: vs lcdf-typetools
+---
+
+# Fontisan vs lcdf-typetools
+
+Compare Fontisan with the lcdf-typetools suite (otfinfo, cfftot1, t1dotlessj, etc.).
+
+## Overview
+
+lcdf-typetools is a C++ suite including:
+- `otfinfo` — Font information
+- `cfftot1` — CFF to Type 1 conversion
+- `t1dotlessj` — Type 1 manipulation
+- `t1reencode` — Type 1 reencoding
+- `ttf2otf` — TTF to OTF conversion
+
+| | lcdf-typetools | Fontisan |
+|---|----------------|----------|
+| Language | C++ | Ruby |
+| Compilation | Required | None |
+| Installation | Complex | `gem install` |
+| Cross-platform | Limited | Full |
+
+## Tool Equivalents
+
+### otfinfo
+
+| otfinfo | Fontisan |
+|---------|----------|
+| `otfinfo -i font.ttf` | `fontisan info font.ttf` |
+| `otfinfo -s font.ttf` | `fontisan info font.ttf --features` |
+| `otfinfo -f font.ttf` | `fontisan info font.ttf --features` |
+| `otfinfo -g font.ttf` | `fontisan info font.ttf --glyphs` |
+| `otfinfo -u font.ttf` | `fontisan info font.ttf --unicode` |
+| `otfinfo -t font.ttf` | `fontisan info font.ttf --tables` |
+
+### cfftot1
+
+| cfftot1 | Fontisan |
+|---------|----------|
+| `cfftot1 font.otf` | `fontisan convert font.otf --to type1 --output font.pfb` |
+
+### t1reencode
+
+| t1reencode | Fontisan |
+|------------|----------|
+| `t1reencode font.pfb` | `fontisan convert font.pfb --to type1 --auto-encoding` |
+
+### ttf2otf
+
+| ttf2otf | Fontisan |
+|---------|----------|
+| `ttf2otf font.ttf` | `fontisan convert font.ttf --to otf --output font.otf` |
+
+## Feature Comparison
+
+### Font Information
+
+| Feature | otfinfo | Fontisan |
+|---------|---------|----------|
+| Basic info | ✅ | ✅ |
+| Script info | ✅ | ✅ |
+| Feature info | ✅ | ✅ |
+| Glyph info | ✅ | ✅ |
+| Unicode info | ✅ | ✅ |
+| Table info | ✅ | ✅ |
+| YAML/JSON | ❌ | ✅ |
+
+### Font Conversion
+
+| Feature | lcdf-typetools | Fontisan |
+|---------|----------------|----------|
+| TTF → OTF | ✅ (ttf2otf) | ✅ |
+| OTF → TTF | ❌ | ✅ |
+| OTF → Type 1 | ✅ (cfftot1) | ✅ |
+| Type 1 → OTF | ❌ | ✅ |
+| TTF → WOFF2 | ❌ | ✅ |
+
+### Hinting
+
+| Feature | lcdf-typetools | Fontisan |
+|---------|----------------|----------|
+| TrueType hints | Read | Read |
+| PostScript hints | Read | Read |
+| Hint conversion | Partial | ✅ |
+| Bidirectional | ❌ | ✅ |
+
+### Validation
+
+| Feature | lcdf-typetools | Fontisan |
+|---------|----------------|----------|
+| Validation | ❌ | ✅ |
+| Profiles | ❌ | ✅ (5) |
+| Helpers | ❌ | ✅ (56) |
+
+### Collections
+
+| Feature | lcdf-typetools | Fontisan |
+|---------|----------------|----------|
+| TTC/OTC reading | ❌ | ✅ |
+| TTC/OTC writing | ❌ | ✅ |
+| dfont support | ❌ | ✅ |
+
+## Unique Features
+
+### Fontisan Unique
+
+- **Pure Ruby** — No C++ compilation
+- **Built-in validation** — Comprehensive checking
+- **Bidirectional hint conversion** — TrueType ↔ PostScript
+- **Full collection support** — TTC/OTC/dfont
+- **Type 1 → OTF** — Reverse conversion
+- **WOFF/WOFF2** — Web font support
+
+### lcdf-typetools Unique
+
+- **t1dotlessj** — Specialized Type 1 manipulation
+- **t1lint** — Type 1 linting
+- **Fast C++** — Native performance
+- **Mature** — Long history
+
+## Installation Comparison
+
+### lcdf-typetools
+
+```bash
+# macOS
+brew install lcdf-typetools
+
+# Linux
+apt install lcdf-typetools
+# or compile from source
+
+# Windows
+# Requires MSYS2 or WSL
+```
+
+### Fontisan
+
+```bash
+# All platforms
+gem install fontisan
+```
+
+## Use Case Recommendations
+
+### Use Fontisan When:
+
+- You need validation
+- You need WOFF/WOFF2
+- You need collection support
+- You want minimal installation
+- You need Type 1 → OTF conversion
+
+### Use lcdf-typetools When:
+
+- You need t1dotlessj
+- You need t1lint
+- You're in a C++ environment
+- You have existing workflows
+
+## Code Comparison
+
+### Get Font Info
+
+```bash
+# otfinfo
+otfinfo -i font.ttf | grep Family
+
+# Fontisan
+fontisan info font.ttf --format json | jq '.family'
+```
+
+### Convert TTF to OTF
+
+```bash
+# ttf2otf
+ttf2otf font.ttf font.otf
+
+# Fontisan
+fontisan convert font.ttf --to otf --output font.otf
+```
+
+### Convert OTF to Type 1
+
+```bash
+# cfftot1
+cfftot1 font.otf font.pfb
+
+# Fontisan
+fontisan convert font.otf --to type1 --output font.pfb
+```
+
+## Conclusion
+
+| Need | Recommendation |
+|------|----------------|
+| Ruby environment | Fontisan |
+| Validation | Fontisan |
+| WOFF/WOFF2 | Fontisan |
+| Collections | Fontisan |
+| t1dotlessj | lcdf-typetools |
+| Type 1 linting | lcdf-typetools |
+| Minimal installation | Fontisan |

data/docs/guide/contributing.md

@@ -0,0 +1,279 @@
+---
+title: Contributing Guide
+---
+
+# Contributing Guide
+
+Thank you for your interest in contributing to Fontisan! This guide covers how to set up your development environment and run tests.
+
+## Development Setup
+
+### Prerequisites
+
+- Ruby 3.0 or higher
+- Bundler gem
+- Git
+
+### Clone and Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/fontist/fontisan.git
+cd fontisan
+
+# Install dependencies
+bundle install
+
+# Verify installation
+bundle exec fontisan version
+```
+
+## Running Tests
+
+### Full Test Suite
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run with documentation format
+bundle exec rspec --format documentation
+
+# Run with progress format (default)
+bundle exec rspec --format progress
+```
+
+### Running Specific Tests
+
+```bash
+# Run specific file
+bundle exec rspec spec/fontisan/tables/maxp_spec.rb
+
+# Run specific test by line number
+bundle exec rspec spec/fontisan/tables/maxp_spec.rb:42
+
+# Run all table tests
+bundle exec rspec spec/fontisan/tables/
+
+# Run all CLI tests
+bundle exec rspec spec/fontisan/cli/
+```
+
+### Running Tests by Tag
+
+```bash
+# Run only unit tests
+bundle exec rspec --tag ~integration
+
+# Run only integration tests
+bundle exec rspec --tag integration
+
+# Run only slow tests
+bundle exec rspec --tag slow
+```
+
+## Test Fixtures
+
+Fontisan uses a centralized fixture configuration system for test fonts.
+
+### Automatic Fixture Download
+
+Test fixtures are automatically downloaded before tests run:
+
+```bash
+# Run tests (fixtures download automatically)
+bundle exec rspec
+
+# Manual fixture management
+bundle exec rake fixtures:download  # Download all test fonts
+bundle exec rake fixtures:clean     # Remove downloaded fonts
+bundle exec rake fixtures:list      # List all fixtures
+```
+
+### Fixture Locations
+
+Fixtures are stored in `spec/fixtures/`:
+
+```
+spec/fixtures/
+├── fonts/
+│   ├── libertinus/        # Libertinus Serif test fonts
+│   ├── MonaSans/          # Mona Sans variable fonts
+│   └── NotoSerifCJK/      # CJK collection fonts
+└── expected/               # Expected output files
+```
+
+### Adding New Fixtures
+
+1. Add fixture URL to `spec/fixtures/fixtures.yml`
+2. Run `bundle exec rake fixtures:download`
+3. Reference in your tests
+
+```ruby
+# Example test using fixture
+RSpec.describe Fontisan::Tables::Maxp do
+  let(:font_path) { 'spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf' }
+
+  it 'reads maxp table' do
+    font = Fontisan::FontLoader.load(font_path)
+    expect(font.table('maxp').num_glyphs).to eq(2731)
+  end
+end
+```
+
+## Test Organization
+
+### Directory Structure
+
+```
+spec/
+├── spec_helper.rb           # Test configuration
+├── fixtures/                # Test font files
+├── fontisan/
+│   ├── cli/                 # CLI command tests
+│   ├── tables/              # OpenType table tests
+│   ├── converters/          # Converter tests
+│   ├── validators/          # Validator tests
+│   └── fontisan_spec.rb     # Main module tests
+└── support/                 # Test helpers and matchers
+```
+
+### Test Categories
+
+| Category | Location | Description |
+|----------|----------|-------------|
+| Unit | `spec/fontisan/` | Individual component tests |
+| Integration | `spec/integration/` | End-to-end workflow tests |
+| CLI | `spec/fontisan/cli/` | Command-line interface tests |
+
+## Writing Tests
+
+### Basic Test Structure
+
+```ruby
+require 'spec_helper'
+
+RSpec.describe Fontisan::Tables::Head do
+  let(:font) { Fontisan::FontLoader.load(fixture_path) }
+  let(:head_table) { font.table('head') }
+
+  describe '#units_per_em' do
+    it 'returns the units per em value' do
+      expect(head_table.units_per_em).to eq(1000)
+    end
+  end
+
+  describe '#valid_magic?' do
+    it 'validates the magic number' do
+      expect(head_table.valid_magic?).to be true
+    end
+  end
+end
+```
+
+### Testing CLI Commands
+
+```ruby
+require 'spec_helper'
+
+RSpec.describe 'fontisan info' do
+  it 'displays font information' do
+    output = `bundle exec fontisan info #{fixture_path}`
+
+    expect(output).to include('Family:')
+    expect(output).to include('Style:')
+  end
+end
+```
+
+### Custom Matchers
+
+Fontisan provides custom RSpec matchers:
+
+```ruby
+# Check if output is valid font
+expect(output_font).to be_valid_font
+
+# Check if font has table
+expect(font).to have_table('head')
+
+# Check if font is valid TrueType
+expect(font).to be_truetype_font
+```
+
+## Debugging Tests
+
+### Verbose Output
+
+```bash
+# Run with verbose output
+bundle exec rspec --format documentation
+
+# Run with backtraces
+bundle exec rspec --backtrace
+```
+
+### Debugging Single Test
+
+```ruby
+# Add to test for debugging
+it 'debugs something' do
+  require 'pry'; binding.pry
+  # Test code here
+end
+```
+
+## Continuous Integration
+
+Tests run automatically on GitHub Actions for:
+
+- Ruby 3.0, 3.1, 3.2, 3.3
+- Ubuntu, macOS, Windows
+
+### CI Configuration
+
+See `.github/workflows/rake.yml` for CI configuration.
+
+## Code Quality
+
+### Linting
+
+```bash
+# Run RuboCop
+bundle exec rubocop
+
+# Auto-correct issues
+bundle exec rubocop -a
+```
+
+### Documentation
+
+```bash
+# Generate YARD documentation
+bundle exec yard doc
+```
+
+## Reporting Issues
+
+When reporting issues, please include:
+
+1. Ruby version (`ruby -v`)
+2. Fontisan version (`fontisan version`)
+3. Sample font file (if possible)
+4. Command that failed
+5. Expected vs actual behavior
+
+## Pull Requests
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new functionality
+4. Ensure all tests pass
+5. Submit pull request
+
+### PR Checklist
+
+- [ ] Tests pass (`bundle exec rspec`)
+- [ ] Code passes linting (`bundle exec rubocop`)
+- [ ] Documentation updated (if applicable)
+- [ ] CHANGELOG updated (if applicable)

data/docs/guide/conversion/collections.md

@@ -0,0 +1,251 @@
+---
+title: Font Collections
+---
+
+# Font Collections
+
+Fontisan supports font collections (TTC, OTC, dfont) with pack, unpack, and format conversion capabilities.
+
+## Overview
+
+| Format | Description | Font Types |
+|--------|-------------|------------|
+| TTC | TrueType Collection | TrueType fonts only |
+| OTC | OpenType Collection | CFF/OpenType fonts only |
+| dfont | Apple Data Fork Font | Mixed TrueType and CFF |
+
+## Listing Fonts in Collections
+
+### CLI
+
+```bash
+# List fonts in a collection
+fontisan ls fonts.ttc
+
+# Output example:
+# Collection: fonts.ttc
+# Fonts: 2
+#
+# 0. Helvetica Regular
+#    PostScript: Helvetica-Regular
+#    Format: TrueType
+#    Glyphs: 268, Tables: 14
+#
+# 1. Helvetica Bold
+#    PostScript: Helvetica-Bold
+#    Format: TrueType
+#    Glyphs: 268, Tables: 14
+```
+
+### API
+
+```ruby
+collection = Fontisan::FontLoader.load('fonts.ttc')
+
+collection.each_with_index do |font, index|
+  puts "#{index}. #{font.family_name} #{font.style}"
+end
+```
+
+## Extracting Fonts (Unpack)
+
+### CLI
+
+```bash
+# Extract all fonts from collection
+fontisan unpack fonts.ttc --output-dir ./extracted
+
+# Extract specific font by index
+fontisan unpack fonts.ttc --index 0 --output first.ttf
+
+# Extract with format conversion
+fontisan unpack fonts.ttc --output-dir ./extracted --format otf
+```
+
+### API
+
+```ruby
+collection = Fontisan::FontLoader.load('fonts.ttc')
+
+collection.each_with_index do |font, index|
+  output = "extracted/font-#{index}.ttf"
+  Fontisan::FontWriter.write(font, output)
+end
+```
+
+## Creating Collections (Pack)
+
+### CLI
+
+```bash
+# Pack fonts into TTC
+fontisan pack font1.ttf font2.ttf font3.ttf --output family.ttc
+
+# Pack with deduplication
+fontisan pack font1.ttf font2.ttf --output family.ttc --deduplicate
+
+# Pack as OTC (OpenType collection)
+fontisan pack font1.otf font2.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')
+```
+
+## Collection Conversions
+
+### TTC → OTC
+
+```ruby
+Fontisan::ConversionOptions.recommended(from: :ttc, to: :otc)
+# opening: { convert_curves: true, decompose_composites: false, autohint: false }
+# generating: { target_format: "otf", decompose_on_output: false,
+#              hinting_mode: "preserve" }
+```
+
+Converts all TrueType fonts to OpenType/CFF, then repacks as OTC.
+
+```bash
+fontisan convert family.ttc --to otc --output family.otc --target-format otf
+```
+
+### OTC → TTC
+
+```ruby
+Fontisan::ConversionOptions.recommended(from: :otc, to: :ttc)
+# opening: { convert_curves: true, decompose_composites: false, interpret_ot: true }
+# generating: { target_format: "ttf", decompose_on_output: false,
+#              hinting_mode: "auto" }
+```
+
+Converts all OpenType/CFF fonts to TrueType, then repacks as TTC.
+
+```bash
+fontisan convert family.otc --to ttc --output family.ttc --target-format ttf
+```
+
+### TTC/OTC → dfont
+
+```ruby
+Fontisan::ConversionOptions.recommended(from: :ttc, to: :dfont)
+# opening: {}
+# generating: { target_format: "preserve", decompose_on_output: false,
+#              write_custom_tables: true }
+```
+
+Notes: dfont supports both TrueType and OpenType/CFF, or mixed formats.
+
+```bash
+fontisan convert family.ttc --to dfont --output family.dfont
+```
+
+## Table Sharing
+
+Collections share common tables to reduce file size:
+
+- `cmap` — Character mappings
+- `loca` — Glyph locations (TrueType)
+- `maxp` — Maximum profile
+- `name` — Font names
+- `post` — PostScript names
+
+### Analyzing Table Sharing
+
+```bash
+fontisan info fonts.ttc
+
+# Output includes:
+# Table Sharing Statistics:
+#   Shared tables: 4
+#   Unique tables per font: 10
+#   Space saved: 45%
+```
+
+## Deduplication
+
+When packing collections, Fontisan can deduplicate tables:
+
+```bash
+fontisan pack font1.ttf font2.ttf --output family.ttc --deduplicate
+```
+
+### How It Works
+
+1. Analyze all tables across fonts
+2. Identify identical tables by checksum
+3. Share tables where possible
+4. Reduce overall file size
+
+## Presets
+
+### archive_to_modern
+
+Convert font archives to modern format:
+
+```ruby
+Fontisan::ConversionOptions.from_preset(:archive_to_modern)
+# From: :ttc, To: :otf
+# opening: { convert_curves: true, decompose_composites: false }
+# generating: { target_format: "otf", hinting_mode: "preserve" }
+```
+
+Use cases:
+- Extracting fonts from TTC archives
+- Standardizing collection formats
+- Converting legacy font collections
+
+## Examples
+
+### Extract and Convert Collection
+
+```bash
+# Extract all fonts as OTF
+fontisan unpack fonts.ttc --output-dir ./family --format otf
+
+# Results in:
+# family/font-0.otf
+# family/font-1.otf
+# family/font-2.otf
+```
+
+### Convert Collection Format
+
+```bash
+# Convert TTC to OTC
+fontisan convert truetype-collection.ttc --to otc \
+  --output opentype-collection.otc \
+  --target-format otf \
+  --hinting-mode auto
+```
+
+### Merge Multiple Collections
+
+```ruby
+# Load multiple collections
+collection1 = Fontisan::FontLoader.load('set1.ttc')
+collection2 = Fontisan::FontLoader.load('set2.ttc')
+
+# Combine fonts
+all_fonts = collection1.to_a + collection2.to_a
+
+# Pack as new collection
+Fontisan::CollectionWriter.pack(all_fonts, 'combined.ttc')
+```
+
+### Optimize Collection
+
+```bash
+# Pack with deduplication
+fontisan pack *.ttf --output optimized.ttc --deduplicate
+
+# Check space savings
+fontisan info optimized.ttc
+```