fontisan 0.2.13 → 0.2.16

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

data/docs/cli/optical-size.md

@@ -0,0 +1,94 @@
+---
+title: optical-size
+---
+
+# optical-size
+
+Show optical size information for a font.
+
+## Quick Reference
+
+```bash
+fontisan optical-size <font> [options]
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--format FORMAT` | Output format (text, yaml, json) |
+
+## What is Optical Size?
+
+Optical sizing is a typographic technique where glyphs are designed differently for different point sizes. Small sizes need more open shapes and spacing, while large sizes can have more detail and tighter spacing.
+
+Variable fonts can use the `opsz` axis for continuous optical sizing, while static fonts may have separate fonts for different size ranges (Caption, Text, Display, etc.).
+
+## Output
+
+Shows:
+- Optical size axis (if variable)
+- Size range recommendations
+- Design size metadata
+- Named instances for sizes
+
+## Examples
+
+```bash
+# Show optical size info
+fontisan optical-size font.ttf
+
+# JSON output
+fontisan optical-size font.ttf --format json
+```
+
+## Sample Output
+
+### Variable Font with opsiz Axis
+
+```
+Optical Size: VariableFont.ttf
+===============================
+
+Axis: opsz (Optical Size)
+  Range: 8pt - 144pt
+  Default: 12pt
+
+Size Recommendations:
+  Caption (6-8pt):    opsz: 8
+  Small Text (9-11pt): opsz: 10
+  Text (12-14pt):     opsz: 12
+  Subhead (14-24pt):  opsz: 18
+  Display (24-72pt):  opsz: 48
+  Poster (72pt+):     opsz: 72
+```
+
+### Static Font with Size Range
+
+```
+Optical Size: FontText-Regular.ttf
+==================================
+
+Design Size: 12pt (Text)
+Size Range: 11-13pt
+Style: Text
+
+Recommended for body text usage.
+```
+
+## Size Categories
+
+| Category | Point Range | Use Case |
+|----------|-------------|----------|
+| Caption | 6-8 | Footnotes, captions |
+| Small Text | 9-11 | Legal text, fine print |
+| Text | 12-14 | Body copy |
+| Subhead | 14-24 | Subheadings |
+| Title | 24-36 | Headings |
+| Display | 36-72 | Large headlines |
+| Poster | 72+ | Very large text |
+
+## Related Commands
+
+- [variable](/cli/variable) — Full variable font info
+- [info](/cli/info) — General font information

data/docs/cli/pack.md

@@ -0,0 +1,125 @@
+---
+title: pack/unpack
+---
+
+# pack/unpack
+
+Work with font collections — TTC, OTC, and dfont formats that contain multiple fonts in a single file.
+
+## What are Font Collections?
+
+Font collections bundle multiple related fonts together:
+
+| Format | Description | Extension |
+|--------|-------------|-----------|
+| TTC | TrueType Collection | `.ttc` |
+| OTC | OpenType Collection (CFF) | `.otc` or `.ttc` |
+| dfont | Apple Data Fork Font | `.dfont` |
+
+Collections save space by sharing common tables (like glyph outlines) across fonts. They're commonly used for font families.
+
+## pack
+
+Create a font collection from multiple individual fonts.
+
+```bash
+fontisan pack <fonts...> --output <collection>
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--output FILE` | Output collection file (.ttc or .otc) |
+| `--deduplicate` | Share common tables to reduce size |
+| `--format TYPE` | Collection type (ttc or otc) |
+
+### Examples
+
+```bash
+# Create a collection from a font family
+fontisan pack Regular.ttf Bold.ttf Italic.ttf --output Family.ttc
+
+# Create with table deduplication (smaller file)
+fontisan pack *.ttf --output fonts.ttc --deduplicate
+
+# Create an OpenType collection (CFF fonts)
+fontisan pack Regular.otf Bold.otf --output fonts.otc
+```
+
+## unpack
+
+Extract individual fonts from a collection.
+
+```bash
+fontisan unpack <collection> [options]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--output-dir DIR` | Output directory for extracted fonts |
+| `--format FORMAT` | Convert to format (ttf, otf, woff, woff2) |
+| `--index N` | Extract only the font at index N |
+| `--font-index N` | Alias for --index |
+
+### Examples
+
+```bash
+# List and extract all fonts
+fontisan unpack fonts.ttc --output-dir ./extracted
+
+# Extract and convert to web formats in one step
+fontisan unpack fonts.ttc --output-dir ./web --format woff2
+
+# Extract a specific font by index
+fontisan unpack fonts.ttc --index 0 --output Regular.ttf
+
+# Extract from Apple dfont
+fontisan unpack fonts.dfont --output-dir ./extracted
+```
+
+## Common Workflows
+
+### Extract Collection for Web Use
+
+```bash
+# Extract and convert to WOFF2 in one command
+fontisan unpack family.ttc --output-dir ./web-fonts --format woff2
+```
+
+### Extract, Modify, and Repack
+
+```bash
+# 1. Extract all fonts
+fontisan unpack family.ttc --output-dir ./working
+
+# 2. Modify fonts (e.g., subset, convert)
+fontisan subset ./working/Regular.ttf --chars "ABC..." --output Regular-subset.ttf
+
+# 3. Repack into new collection
+fontisan pack *-subset.ttf --output family-subset.ttc --deduplicate
+```
+
+### Convert Collection Format
+
+```bash
+# Extract from dfont, repack as TTC
+fontisan unpack fonts.dfont --output-dir ./temp
+fontisan pack ./temp/*.ttf --output fonts.ttc
+```
+
+### View Collection Contents
+
+```bash
+# List fonts in a collection
+fontisan ls fonts.ttc
+
+# Get detailed info
+fontisan info fonts.ttc
+```
+
+## Detailed Documentation
+
+For comprehensive documentation including table sharing analysis and advanced options, see the [pack/unpack command guide](/guide/cli/pack).