fontisan 0.2.14 → 0.2.17

data/docs/guide/cli/pack.md

@@ -0,0 +1,155 @@
+---
+title: pack/unpack
+---
+
+# pack/unpack
+
+Create and extract font collections.
+
+## pack
+
+Create font collections.
+
+### Usage
+
+```bash
+fontisan pack FONT ... --output COLLECTION [options]
+```
+
+### Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `FONT ...` | Input font files |
+| `--output PATH` | Output collection |
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--deduplicate` | Deduplicate tables |
+| `--format FORMAT` | Collection format (ttc, otc, dfont) |
+
+### Examples
+
+```bash
+# Create TTC
+fontisan pack regular.ttf bold.ttf italic.ttf --output family.ttc
+
+# Create OTC
+fontisan pack regular.otf bold.otf --output family.otc
+
+# With deduplication
+fontisan pack *.ttf --output family.ttc --deduplicate
+
+# Create dfont
+fontisan pack regular.ttf bold.ttf --output family.dfont
+```
+
+## unpack
+
+Extract fonts from collections.
+
+### Usage
+
+```bash
+fontisan unpack COLLECTION [options]
+```
+
+### Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `COLLECTION` | Collection file |
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--output-dir DIR` | Output directory |
+| `--index N` | Extract specific font |
+| `--output PATH` | Output file (with --index) |
+| `--format FORMAT` | Convert to format |
+
+### Examples
+
+```bash
+# Extract all to directory
+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
+
+# Extract from dfont
+fontisan unpack font.dfont --output-dir ./fonts
+```
+
+## ls
+
+List fonts in collections.
+
+### Usage
+
+```bash
+fontisan ls COLLECTION
+```
+
+### Examples
+
+```bash
+fontisan ls family.ttc
+
+# Collection: family.ttc
+# Fonts: 4
+#
+# 0. Family Regular
+#    PostScript: Family-Regular
+#    Format: TrueType
+#    Glyphs: 268, Tables: 14
+#
+# 1. Family Bold
+#    PostScript: Family-Bold
+#    Format: TrueType
+#    Glyphs: 268, Tables: 14
+```
+
+## Workflow Examples
+
+### Extract, Modify, Repack
+
+```bash
+# Extract
+fontisan unpack family.ttc --output-dir ./temp
+
+# Modify fonts...
+
+# Repack
+fontisan pack temp/*.ttf --output family-new.ttc --deduplicate
+```
+
+### Convert Collection Format
+
+```bash
+# TTC to OTC
+fontisan unpack family.ttc --output-dir ./temp --format otf
+fontisan pack temp/*.otf --output family.otc
+
+# Or directly
+fontisan convert family.ttc --to otc --output family.otc
+```
+
+### Analyze Collection
+
+```bash
+# List contents
+fontisan ls family.ttc
+
+# Get info
+fontisan info family.ttc
+
+# Validate all
+fontisan validate family.ttc
+```

data/docs/guide/cli/subset.md

@@ -0,0 +1,118 @@
+---
+title: subset
+---
+
+# subset
+
+Create font subsets.
+
+## Usage
+
+```bash
+fontisan subset FONT [options]
+```
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `FONT` | Input font file |
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--chars TEXT` | Characters to include |
+| `--chars-file PATH` | File with characters |
+| `--unicodes RANGE` | Unicode ranges |
+| `--glyphs LIST` | Glyph names/IDs |
+| `--output PATH` | Output file |
+| `--output-format FORMAT` | Output format |
+| `--retain-gids` | Retain glyph IDs |
+
+## Examples
+
+### By Characters
+
+```bash
+# Subset to specific characters
+fontisan subset font.ttf --chars "ABCDEFabcdef0123456789" --output subset.ttf
+
+# Subset to ASCII
+fontisan subset font.ttf --chars "$(printf '%s' {a..z} {A..Z} {0..9})" --output ascii.ttf
+```
+
+### By Unicode Range
+
+```bash
+# Basic Latin only
+fontisan subset font.ttf --unicodes "U+0000-007F" --output basic-latin.ttf
+
+# Latin + Latin-1
+fontisan subset font.ttf --unicodes "U+0000-00FF" --output latin1.ttf
+
+# Multiple ranges
+fontisan subset font.ttf --unicodes "U+0000-007F,U+00A0-00FF" --output extended.ttf
+```
+
+### By Glyph Names
+
+```bash
+# Specific glyphs
+fontisan subset font.ttf --glyphs "A,B,C,a,b,c,zero,one,two" --output subset.ttf
+```
+
+### From File
+
+```bash
+# Read characters from file
+echo "Hello World" > chars.txt
+fontisan subset font.ttf --chars-file chars.txt --output subset.ttf
+```
+
+### Retain Glyph IDs
+
+```bash
+# Keep original glyph IDs
+fontisan subset font.ttf --chars "ABC" --retain-gids --output subset.ttf
+```
+
+### With Format Conversion
+
+```bash
+# Subset and convert to WOFF2
+fontisan subset font.ttf --chars "ABC" --output-format woff2 --output subset.woff2
+```
+
+## Subsetting Strategies
+
+### Web Font Optimization
+
+```bash
+# Subset to page content
+fontisan subset font.ttf --chars "$(cat content.html)" --output web-font.woff2
+```
+
+### Latin Only
+
+```bash
+# Standard Latin subset
+fontisan subset font.ttf --unicodes "U+0000-024F,U+1E00-1EFF" --output latin.woff2
+```
+
+### Character Set Presets
+
+```bash
+# ASCII
+fontisan subset font.ttf --unicodes "U+0000-007F" --output ascii.ttf
+
+# Basic Multilingual Plane (BMP)
+fontisan subset font.ttf --unicodes "U+0000-FFFF" --output bmp.ttf
+```
+
+## Notes
+
+- Subsetting removes unused glyphs and tables
+- CFF fonts may require special handling
+- Variable fonts are subset while preserving variation
+- OpenType features are preserved for included glyphs

data/docs/guide/cli/validate.md

@@ -0,0 +1,139 @@
+---
+title: validate
+---
+
+# validate
+
+Validate fonts for correctness.
+
+## Usage
+
+```bash
+fontisan validate FONT [options]
+```
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `FONT` | Font file to validate |
+| `FONT ...` | Multiple files |
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `-t, --profile PROFILE` | Validation profile |
+| `-S, --summary` | Show summary only |
+| `-T, --table` | Table format output |
+| `--list` | List available profiles |
+
+## Profiles
+
+| Profile | Description |
+|---------|-------------|
+| `indexability` | Fast font discovery |
+| `usability` | Installation compatibility |
+| `production` | Comprehensive quality (default) |
+| `web` | Web embedding readiness |
+| `spec_compliance` | Full spec compliance |
+
+## Examples
+
+### Basic Validation
+
+```bash
+fontisan validate font.ttf
+
+# Font: font.ttf
+# Status: VALID
+#
+# Summary:
+#   Checks performed: 37
+#   Passed: 37
+#   Failed: 0
+```
+
+### With Profile
+
+```bash
+fontisan validate font.ttf -t web
+
+# Font: font.ttf
+# Profile: web
+# Status: INVALID
+#
+# Summary:
+#   Checks performed: 18
+#   Passed: 17
+#   Failed: 1
+#
+# Failed checks:
+#   web_font_tables - Missing required GSUB table
+```
+
+### Summary Only
+
+```bash
+fontisan validate font.ttf -S
+
+# font.ttf: VALID (37/37 checks passed)
+```
+
+### Table Format
+
+```bash
+fontisan validate font.ttf -T
+
+# CHECK_ID            | STATUS | SEVERITY | TABLE
+# --------------------------------------------------
+# required_tables     | PASS   | error    | N/A
+# name_version        | PASS   | error    | name
+# family_name         | PASS   | error    | name
+# head_magic          | PASS   | error    | head
+# ...
+```
+
+### Multiple Files
+
+```bash
+fontisan validate fonts/*.ttf
+
+# fonts/regular.ttf: VALID
+# fonts/bold.ttf: VALID
+# fonts/italic.ttf: INVALID (1 error)
+```
+
+### List Profiles
+
+```bash
+fontisan validate --list
+
+# Available validation profiles:
+#   indexability    - Fast validation for font discovery
+#   usability       - Basic usability for installation
+#   production      - Comprehensive quality checks
+#   web             - Web embedding and optimization
+#   spec_compliance - Full OpenType spec compliance
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Valid |
+| 1 | Invalid (errors found) |
+| 2 | Error (file not found, etc.) |
+
+## Use in Scripts
+
+```bash
+# Validate before release
+fontisan validate font.ttf -t production
+if [ $? -eq 0 ]; then
+  echo "Ready for release"
+else
+  echo "Validation failed"
+  exit 1
+fi
+```

data/docs/guide/color-fonts/bitmaps.md

@@ -0,0 +1,177 @@
+---
+title: Bitmap Color Fonts
+---
+
+# Bitmap Color Fonts
+
+Bitmap color fonts store pixel images at specific sizes.
+
+## Formats
+
+| Format | Tables | Platform |
+|--------|--------|----------|
+| sbix | sbix | Apple |
+| CBDT/CBLC | CBDT, CBLC | Google/Android |
+
+## sbix (Apple)
+
+sbix stores bitmap images at multiple resolutions.
+
+### Structure
+
+```ruby
+sbix = font.tables['sbix']
+
+# Strikes (image sets at different sizes)
+sbix.strikes.each do |strike|
+  puts "Strike at #{strike.ppem} ppem"
+
+  strike.glyphs.each do |glyph_id, image|
+    puts "  Glyph #{glyph_id}: #{image.format}"
+  end
+end
+```
+
+### Image Formats
+
+- `png ` — PNG image
+- `jpg ` — JPEG image
+- `tiff` — TIFF image
+- `dupe` — Duplicate of another glyph
+
+### Accessing Images
+
+```ruby
+sbix = font.tables['sbix']
+strike = sbix.strikes.first
+
+glyph_id = 42
+image = strike.image_for(glyph_id)
+
+puts "Format: #{image.format}"
+puts "Data size: #{image.data.length} bytes"
+```
+
+## CBDT/CBLC (Android)
+
+CBDT/CBLC stores bitmap images for Android.
+
+### Structure
+
+```ruby
+cbdt = font.tables['CBDT']
+cblc = font.tables['CBLC']
+
+# CBLC has location data
+cblc.strikes.each do |strike|
+  puts "Strike at #{strike.ppem}x#{strike.ppem}"
+
+  strike.glyph_ranges.each do |range|
+    puts "  Glyphs #{range.start}..#{range.end}"
+  end
+end
+
+# CBDT has actual bitmap data
+```
+
+### Bitmap Formats
+
+- **Small metrics** — For small glyphs
+- **Big metrics** — For larger glyphs
+- **Bit aligned** — 1, 2, 4, or 8 bits per pixel
+
+### Accessing Bitmaps
+
+```ruby
+cbdt = font.tables['CBDT']
+cblc = font.tables['CBLC']
+
+glyph_id = 42
+strike_index = 0
+
+# Get bitmap location
+location = cblc.location(strike_index, glyph_id)
+
+if location
+  # Get bitmap data
+  bitmap = cbdt.bitmap(location)
+  puts "Size: #{bitmap.width}x#{bitmap.height}"
+  puts "Data: #{bitmap.data.length} bytes"
+end
+```
+
+## Working with Bitmaps
+
+### List Available Sizes
+
+```ruby
+sbix = font.tables['sbix']
+
+if sbix
+  puts "Available sizes:"
+  sbix.strikes.each do |strike|
+    puts "  #{strike.ppem} ppem"
+  end
+end
+```
+
+### Export Bitmaps
+
+```ruby
+sbix = font.tables['sbix']
+strike = sbix.strikes.first
+
+sbix.glyphs.each do |glyph_id, image|
+  if image.format == 'png '
+    File.write("glyph-#{glyph_id}.png", image.data)
+  end
+end
+```
+
+## Conversion
+
+### Preserve Bitmaps
+
+```bash
+# Bitmaps preserved during same-format conversion
+fontisan convert bitmap-font.ttf --to ttf --output bitmap-font.ttf
+```
+
+### Remove Bitmaps
+
+```bash
+# Create outline-only version
+fontisan convert bitmap-font.ttf --to ttf --no-bitmaps --output outline-only.ttf
+```
+
+## Comparison
+
+| Feature | sbix | CBDT/CBLC |
+|---------|------|-----------|
+| Platform | Apple | Android |
+| Image formats | PNG, JPEG, TIFF | Raw bitmap |
+| Scalability | No | No |
+| File size | Larger | Smaller |
+| Quality | Photo-realistic | Limited |
+
+## Limitations
+
+### Bitmap Scaling
+
+Bitmap fonts don't scale well:
+- Each strike is designed for a specific ppem
+- Scaling up causes pixelation
+- Scaling down causes aliasing
+
+### Variable Fonts
+
+Bitmap fonts don't work with variation:
+- No interpolation possible
+- Must provide strikes for each instance
+
+## Best Practices
+
+1. **Provide multiple strikes** — Cover common sizes
+2. **Use PNG for sbix** — Best quality/size tradeoff
+3. **Test on target platforms** — Rendering varies
+4. **Consider outline fallback** — For unavailable sizes