fontisan 0.2.14 → 0.2.16

data/docs/cli/index.md

@@ -0,0 +1,208 @@
+---
+title: CLI Reference
+---
+
+# CLI Reference
+
+Fontisan provides a comprehensive command-line interface for font processing tasks.
+
+::: 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.
+:::
+
+## Quick Reference
+
+### Font Information Commands
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `info` | Get comprehensive font information | `fontisan info font.ttf` |
+| `ls` | List fonts in a collection | `fontisan ls fonts.ttc` |
+| `tables` | Show font table information | `fontisan tables font.ttf` |
+| `glyphs` | List glyphs with names and IDs | `fontisan glyphs font.ttf` |
+| `unicode` | Show Unicode coverage | `fontisan unicode font.ttf` |
+| `scripts` | List supported scripts | `fontisan scripts font.ttf` |
+| `features` | List OpenType features | `fontisan features font.ttf` |
+| `variable` | Show variable font axes | `fontisan variable font.ttf` |
+| `optical-size` | Show optical size info | `fontisan optical-size font.ttf` |
+
+### Font Operations
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `convert` | Convert between formats | `fontisan convert input.ttf --to otf` |
+| `subset` | Subset fonts | `fontisan subset font.ttf --chars "ABC"` |
+| `validate` | Validate fonts | `fontisan validate font.ttf` |
+| `instance` | Generate variable font instances | `fontisan instance var.ttf --wght 700` |
+| `dump-table` | Extract raw table data | `fontisan dump-table font.ttf head` |
+
+### Collection Operations
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `pack` | Create font collections | `fontisan pack *.ttf -o fonts.ttc` |
+| `unpack` | Extract from collections | `fontisan unpack fonts.ttc -d ./out` |
+
+### Export Operations
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `export` | Export to TTX, SVG, JSON | `fontisan export font.ttf --format ttx` |
+
+## Global Options
+
+```bash
+fontisan [options] <command>
+
+Options:
+  --format FORMAT    Output format (text, yaml, json)
+  --verbose          Verbose output
+  --quiet            Suppress non-error output
+  --help             Show help
+  --version          Show version
+```
+
+## Getting Help
+
+```bash
+# General help
+fontisan --help
+
+# Command-specific help
+fontisan convert --help
+fontisan validate --help
+fontisan instance --help
+```
+
+## Output Formats
+
+Most commands support multiple output formats:
+
+```bash
+# Text (default)
+fontisan info font.ttf
+
+# YAML
+fontisan info font.ttf --format yaml
+
+# JSON
+fontisan info font.ttf --format json
+```
+
+## Common Workflows
+
+### Inspect a Font
+
+```bash
+# Basic information
+fontisan info font.ttf
+
+# Detailed table listing
+fontisan tables font.ttf
+
+# See all glyphs
+fontisan glyphs font.ttf
+
+# Check Unicode coverage
+fontisan unicode font.ttf
+```
+
+### Convert for Web
+
+```bash
+# Convert single font to WOFF2
+fontisan convert font.ttf --to woff2 --output font.woff2
+```
+
+### Work with Variable Fonts
+
+```bash
+# Inspect variable font axes
+fontisan variable VariableFont.ttf
+
+# Generate a specific instance
+fontisan instance VariableFont.ttf --wght 700 --output Bold.ttf
+
+# Generate multiple instances
+fontisan instance VariableFont.ttf --wght 400 --output Regular.ttf
+fontisan instance VariableFont.ttf --wght 700 --output Bold.ttf
+```
+
+### Work with Collections
+
+```bash
+# List fonts in collection
+fontisan ls fonts.ttc
+
+# Extract all fonts
+fontisan unpack fonts.ttc --output-dir ./extracted
+
+# Extract and convert to web formats
+fontisan unpack fonts.ttc --output-dir ./web --format woff2
+
+# Create a collection
+fontisan pack Regular.ttf Bold.ttf --output Family.ttc
+```
+
+### Validate Fonts
+
+```bash
+# Quick validation
+fontisan validate font.ttf
+
+# Validate for Google Fonts
+fontisan validate font.ttf --profile google_fonts
+
+# Strict validation
+fontisan validate font.ttf --profile production
+```
+
+### Export Font Data
+
+```bash
+# Export to TTX (XML format)
+fontisan export font.ttf --format ttx --output font.ttx
+
+# Export to JSON
+fontisan export font.ttf --format json --output font.json
+
+# Export specific tables
+fontisan export font.ttf --format ttx --tables head,name,cmap
+```
+
+## Command Documentation
+
+Detailed documentation for each command:
+
+### Font Information
+- [info](/cli/info) — Extract font metadata and properties (includes brief mode)
+- [ls](/cli/ls) — List fonts in collections
+- [tables](/cli/tables) — Show OpenType table directory
+- [glyphs](/cli/glyphs) — List glyph names and indices
+- [unicode](/cli/unicode) — Show Unicode character mappings
+- [scripts](/cli/scripts) — List supported writing scripts
+- [features](/cli/features) — List OpenType layout features
+- [variable](/cli/variable) — Show variable font axes and instances
+- [optical-size](/cli/optical-size) — Display optical size information
+
+### Font Operations
+- [convert](/cli/convert) — Format conversion (TTF, OTF, WOFF, WOFF2)
+- [subset](/cli/subset) — Create character subsets
+- [validate](/cli/validate) — Validate fonts against profiles
+- [instance](/cli/instance) — Generate static instances from variable fonts
+- [export](/cli/export) — Export to TTX, YAML, JSON
+- [dump-table](/cli/dump-table) — Extract raw binary table data
+
+### Collection Operations
+- [pack](/cli/pack) — Create and extract font collections (TTC/OTC)
+
+### Utilities
+- [version](/cli/version) — Show Fontisan version

data/docs/cli/info.md

@@ -0,0 +1,254 @@
+---
+title: info
+---
+
+# info
+
+Get comprehensive font information.
+
+## Quick Reference
+
+```bash
+fontisan info <font> [options]
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--format FORMAT` | Output format (text, yaml, json) |
+| `--brief` | Fast mode - essential metadata only (5x faster) |
+| `--verbose` | Show all available information |
+| `--tables` | Include table listing |
+| `--features` | Include OpenType features |
+
+## Brief Mode
+
+For font indexing systems that need to scan thousands of fonts quickly, use the `--brief` flag to get essential metadata only.
+
+### Performance Benefits
+
+- **5x faster** than full mode by using metadata-only loading
+- **Loads only 6 tables** instead of 15-20 (name, head, hhea, maxp, OS/2, post)
+- **Lower memory usage** through reduced table loading
+- **Optimized for batch processing** of many fonts
+
+### Brief Mode Attributes
+
+Brief mode populates only the following 13 essential attributes:
+
+**Font Identification:**
+- `font_format` - Font format (truetype, cff)
+- `is_variable` - Whether font is variable
+
+**Essential Names:**
+- `family_name` - Font family name
+- `subfamily_name` - Font subfamily/style
+- `full_name` - Full font name
+- `postscript_name` - PostScript name
+
+**Version Info:**
+- `version` - Version string
+
+**Metrics:**
+- `font_revision` - Font revision number
+- `units_per_em` - Units per em
+
+**Vendor:**
+- `vendor_id` - Vendor/foundry ID
+
+### Brief Mode Examples
+
+```bash
+# Fast font indexing
+fontisan info font.ttf --brief
+
+# Brief mode with JSON output
+fontisan info font.ttf --brief --format json
+
+# Process many fonts quickly
+for font in *.ttf; do
+  fontisan info "$font" --brief --format json >> fonts.jsonl
+done
+```
+
+### Brief Mode Sample Output
+
+```
+Font type:                TrueType (Variable)
+Family:                   Mona Sans ExtraLight
+Subfamily:                Regular
+Full name:                Mona Sans ExtraLight
+PostScript name:          MonaSans-ExtraLight
+Version:                  Version 2.001
+Vendor ID:                GTHB
+Font revision:            2.00101
+Units per em:             1000
+```
+
+### Brief Mode JSON Output
+
+```json
+{
+  "font_format": "truetype",
+  "is_variable": true,
+  "family_name": "Mona Sans ExtraLight",
+  "subfamily_name": "Regular",
+  "full_name": "Mona Sans ExtraLight",
+  "postscript_name": "MonaSans-ExtraLight",
+  "version": "Version 2.001",
+  "font_revision": 2.00101,
+  "vendor_id": "GTHB",
+  "units_per_em": 1000
+}
+```
+
+## Full Mode
+
+Full mode populates additional attributes (remain `nil` in brief mode):
+
+- `postscript_cid_name`, `preferred_family`, `preferred_subfamily`, `mac_font_menu_name`
+- `unique_id`, `description`, `designer`, `designer_url`
+- `manufacturer`, `vendor_url`, `trademark`, `copyright`
+- `license_description`, `license_url`, `sample_text`, `permissions`
+
+## Output
+
+Shows comprehensive font metadata:
+- Family and style names
+- Version and copyright
+- PostScript name
+- Format (TrueType, OpenType, etc.)
+- Glyph count
+- Table count
+- Unicode ranges
+- Variable font axes (if applicable)
+
+## Examples
+
+```bash
+# Basic info
+fontisan info font.ttf
+
+# Brief mode for fast indexing
+fontisan info font.ttf --brief
+
+# Verbose output
+fontisan info font.ttf --verbose
+
+# Include tables
+fontisan info font.ttf --tables
+
+# JSON output
+fontisan info font.ttf --format json
+```
+
+## Sample Output
+
+```
+Font: SourceSans3-Regular.otf
+Format: OpenType (CFF)
+Family: Source Sans 3
+Style: Regular
+PostScript: SourceSans3-Regular
+Version: 3.046
+Copyright: Copyright 2023 Adobe
+
+Glyphs: 1,024
+Tables: 18
+Characters: 892
+
+Unicode Ranges:
+  Basic Latin (95)
+  Latin-1 Supplement (96)
+  Latin Extended-A (128)
+  Greek and Coptic (72)
+
+Features: 24
+  liga, dlig, kern, mark, mkmk, ...
+```
+
+## Use Cases
+
+### Get Family Name
+
+```bash
+fontisan info font.ttf --format json | jq '.family_name'
+```
+
+### Check Font Format
+
+```bash
+fontisan info font.ttf --format json | jq '.format'
+```
+
+### Compare Fonts
+
+```bash
+diff <(fontisan info font1.ttf) <(fontisan info font2.ttf)
+```
+
+### Batch Process Fonts (Fast)
+
+```bash
+# Use brief mode for fast batch processing
+for font in *.ttf; do
+  echo "=== $font ==="
+  fontisan info "$font" --brief
+done
+```
+
+### Build Font Index
+
+```bash
+# Create JSON index of all fonts
+echo '[' > fonts.json
+first=true
+for font in **/*.ttf; do
+  if $first; then first=false; else echo ',' >> fonts.json; fi
+  fontisan info "$font" --brief --format json >> fonts.json
+done
+echo ']' >> fonts.json
+```
+
+## Ruby API
+
+### Brief Mode
+
+```ruby
+require 'fontisan'
+
+# Fast metadata-only loading
+info = Fontisan.info("font.ttf", brief: true)
+
+# Access populated fields
+puts info.family_name       # "Open Sans"
+puts info.postscript_name   # "OpenSans-Regular"
+puts info.is_variable       # false
+
+# Non-essential fields are nil
+puts info.copyright         # nil (not populated)
+puts info.designer          # nil (not populated)
+
+# Serialize to YAML/JSON
+puts info.to_yaml
+puts info.to_json
+```
+
+### Brief Mode for Collections
+
+```ruby
+require 'fontisan'
+
+# Specify font index for TTC/OTC files
+info = Fontisan.info("/path/to/fonts.ttc", brief: true, font_index: 0)
+puts info.family_name
+```
+
+## Related Commands
+
+- [tables](/cli/tables) — Detailed table information
+- [glyphs](/cli/glyphs) — List all glyphs
+- [features](/cli/features) — List OpenType features
+- [variable](/cli/variable) — Variable font details
+- [version](/cli/version) — Show Fontisan version

data/docs/cli/instance.md

@@ -0,0 +1,122 @@
+---
+title: instance
+---
+
+# instance
+
+Generate static font instances from variable fonts.
+
+::: warning License Consideration
+Many commercial variable fonts require a special license to generate static instances. Check your font's EULA before using this command.
+:::
+
+## Quick Reference
+
+```bash
+fontisan instance <variable-font> [options]
+```
+
+## What are Variable Font Instances?
+
+Variable fonts contain multiple variations along design axes (weight, width, slant, etc.). The `instance` command extracts a specific variation as a standalone static font.
+
+For example, a variable font with a `wght` (weight) axis from 100-900 can generate instances like:
+- Light (wght: 300)
+- Regular (wght: 400)
+- Medium (wght: 500)
+- Bold (wght: 700)
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--output FILE` | Output file path |
+| `--wght VALUE` | Weight axis value (e.g., 400, 700) |
+| `--wdth VALUE` | Width axis value |
+| `--slnt VALUE` | Slant axis value |
+| `--ital VALUE` | Italic axis value |
+| `--opsz VALUE` | Optical size axis value |
+| `--named INSTANCE` | Use named instance (e.g., "Bold") |
+| `--format FORMAT` | Output format (ttf, otf, woff, woff2) |
+
+## Examples
+
+### Generate by Axis Values
+
+```bash
+# Generate Regular weight
+fontisan instance VariableFont.ttf --wght 400 --output Regular.ttf
+
+# Generate Bold weight
+fontisan instance VariableFont.ttf --wght 700 --output Bold.ttf
+
+# Generate with multiple axes
+fontisan instance VariableFont.ttf --wght 500 --wdth 75 --output MediumCondensed.ttf
+
+# Generate with optical size
+fontisan instance VariableFont.ttf --wght 400 --opsz 12 --output Text-12pt.ttf
+```
+
+### Generate by Named Instance
+
+```bash
+# Use a named instance from the font
+fontisan instance VariableFont.ttf --named "Bold" --output Bold.ttf
+
+# List available named instances first
+fontisan variable VariableFont.ttf
+```
+
+### Generate for Web
+
+```bash
+# Generate and convert to WOFF2 in one step
+fontisan instance VariableFont.ttf --wght 400 --format woff2 --output Regular.woff2
+fontisan instance VariableFont.ttf --wght 700 --format woff2 --output Bold.woff2
+```
+
+### Batch Generation
+
+```bash
+# Generate common weights
+for wght in 300 400 500 600 700; do
+  fontisan instance VariableFont.ttf --wght $wght --output Font-$wght.ttf
+done
+```
+
+## Common Axes
+
+| Axis Tag | Name | Typical Range |
+|----------|------|---------------|
+| `wght` | Weight | 1-999 (100-900 common) |
+| `wdth` | Width | 0-200 (% of normal) |
+| `slnt` | Slant | -90 to +90 (degrees) |
+| `ital` | Italic | 0-1 |
+| `opsz` | Optical Size | 8-144 (point size) |
+| `GRAD` | Grade | -1 to 1 |
+| `XTRA` | X-height | Various |
+| `XOPQ` | X opaque | Various |
+| `YOPQ` | Y opaque | Various |
+
+## Discovering Axes
+
+Use the `variable` command to see what axes a font has:
+
+```bash
+fontisan variable VariableFont.ttf
+```
+
+Output shows:
+- Available axes with their ranges
+- Named instances defined in the font
+- Default values
+
+## Detailed Documentation
+
+For comprehensive documentation including:
+- How variable fonts work
+- Instance generation algorithms
+- Handling complex axes
+- Format conversion options
+
+See the [Variable Fonts Guide](/guide/variable-fonts/).

data/docs/cli/ls.md

@@ -0,0 +1,95 @@
+---
+title: ls
+---
+
+# ls
+
+List fonts in a collection.
+
+## Quick Reference
+
+```bash
+fontisan ls <collection> [options]
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--format FORMAT` | Output format (text, yaml, json) |
+| `--verbose` | Show detailed information |
+
+## Supported Collections
+
+- TTC (TrueType Collection)
+- OTC (OpenType Collection)
+- dfont (Apple Data Fork Font)
+
+## Examples
+
+```bash
+# List fonts in a TTC
+fontisan ls fonts.ttc
+
+# List fonts in a dfont
+fontisan ls fonts.dfont
+
+# JSON output
+fontisan ls fonts.ttc --format json
+
+# Verbose output
+fontisan ls fonts.ttc --verbose
+```
+
+## Sample Output
+
+```
+Collection: fonts.ttc
+Fonts: 4
+
+0. Noto Serif CJK JP
+   PostScript: NotoSerifCJKJP-Regular
+   Format: OpenType
+   Glyphs: 65,535
+
+1. Noto Serif CJK KR
+   PostScript: NotoSerifCJKKR-Regular
+   Format: OpenType
+   Glyphs: 65,535
+
+2. Noto Serif CJK SC
+   PostScript: NotoSerifCJKSC-Regular
+   Format: OpenType
+   Glyphs: 65,535
+
+3. Noto Serif CJK TC
+   PostScript: NotoSerifCJKTC-Regular
+   Format: OpenType
+   Glyphs: 65,535
+```
+
+## Use Cases
+
+### Count Fonts in Collection
+
+```bash
+fontisan ls fonts.ttc | grep -c "PostScript"
+```
+
+### Get Font Index for Extraction
+
+```bash
+# Find the index of a specific font
+fontisan ls fonts.ttc | grep -n "Bold"
+```
+
+### Extract Collection Info to JSON
+
+```bash
+fontisan ls fonts.ttc --format json > collection-info.json
+```
+
+## Related Commands
+
+- [pack/unpack](/cli/pack) — Create and extract collections
+- [info](/cli/info) — Get detailed font information