fontisan 0.2.14 → 0.2.16

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).

data/docs/cli/scripts.md

@@ -0,0 +1,105 @@
+---
+title: scripts
+---
+
+# scripts
+
+List scripts and languages supported by a font.
+
+## Quick Reference
+
+```bash
+fontisan scripts <font> [options]
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--format FORMAT` | Output format (text, yaml, json) |
+| `--with-languages` | Include language systems |
+| `--with-features` | Include features per script |
+
+## Output
+
+Shows:
+- Script tags (OpenType 4-character codes)
+- Script names
+- Language systems (optional)
+- Feature count per script
+
+## Examples
+
+```bash
+# List scripts
+fontisan scripts font.ttf
+
+# With language systems
+fontisan scripts font.ttf --with-languages
+
+# With features
+fontisan scripts font.ttf --with-features
+
+# JSON output
+fontisan scripts font.ttf --format json
+```
+
+## Sample Output
+
+```
+Scripts
+=======
+
+Tag     Name                    Languages  Features
+------  ----------------------  ---------  --------
+DFLT    Default                 1          12
+latn    Latin                   27         45
+cyrl    Cyrillic                8          32
+grek    Greek                   2          28
+arab    Arabic                  4          38
+
+Total: 5 scripts, 42 language systems
+```
+
+## Common Script Tags
+
+| Tag | Script |
+|-----|--------|
+| `DFLT` | Default |
+| `latn` | Latin |
+| `cyrl` | Cyrillic |
+| `grek` | Greek |
+| `arab` | Arabic |
+| `hebr` | Hebrew |
+| `deva` | Devanagari |
+| `beng` | Bengali |
+| `hans` | Simplified Chinese |
+| `hant` | Traditional Chinese |
+| `jpan` | Japanese |
+| `kore` | Korean |
+| `thai` | Thai |
+
+## Use Cases
+
+### Check for Script Support
+
+```bash
+fontisan scripts font.ttf | grep -i arab
+```
+
+### Verify Multi-script Font
+
+```bash
+fontisan scripts font.ttf --format json | jq 'length'
+```
+
+### Compare Script Coverage
+
+```bash
+diff <(fontisan scripts font1.ttf) <(fontisan scripts font2.ttf)
+```
+
+## Related Commands
+
+- [features](/cli/features) — List OpenType features
+- [unicode](/cli/unicode) — Show Unicode coverage

data/docs/cli/subset.md

@@ -0,0 +1,39 @@
+---
+title: subset
+---
+
+# subset
+
+Create font subsets with reduced character sets.
+
+## Quick Reference
+
+```bash
+fontisan subset <font> [options]
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--chars TEXT` | Characters to include |
+| `--file FILE` | File containing characters |
+| `--output FILE` | Output file path |
+| `--format FORMAT` | Output format |
+
+## Examples
+
+```bash
+# Subset to specific characters
+fontisan subset font.ttf --chars "ABCDEF" --output subset.ttf
+
+# Subset from file
+fontisan subset font.ttf --file chars.txt --output subset.ttf
+
+# Subset and convert format
+fontisan subset font.ttf --chars "Hello" --format woff2
+```
+
+## Detailed Documentation
+
+For comprehensive documentation including unicode ranges and advanced subsetting, see the [subset command guide](/guide/cli/subset).

data/docs/cli/tables.md

@@ -0,0 +1,84 @@
+---
+title: tables
+---
+
+# tables
+
+Show font table information.
+
+## Quick Reference
+
+```bash
+fontisan tables <font> [options]
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--format FORMAT` | Output format (text, yaml, json) |
+| `--detail` | Show detailed table info |
+| `--checksums` | Include checksums |
+
+## Output
+
+Lists all tables in the font with:
+- Table tag (4-character identifier)
+- Checksum
+- Offset
+- Length
+
+## Examples
+
+```bash
+# List all tables
+fontisan tables font.ttf
+
+# With checksums
+fontisan tables font.ttf --checksums
+
+# Detailed information
+fontisan tables font.ttf --detail
+
+# JSON output
+fontisan tables font.ttf --format json
+```
+
+## Sample Output
+
+```
+Tag    Checksum    Offset    Length
+-----  ----------  --------  --------
+head   0x12345678  0         54
+hhea   0x23456789  54        36
+maxp   0x3456789A  90        32
+OS/2   0x456789AB  122       96
+name   0x56789ABC  218       1024
+cmap   0x6789ABCD  1242      2048
+...
+```
+
+## Common Tables
+
+| Tag | Name | Purpose |
+|-----|------|---------|
+| `head` | Font Header | Global font info |
+| `hhea` | Horizontal Header | Horizontal metrics |
+| `maxp` | Maximum Profile | Font requirements |
+| `OS/2` | OS/2 | Windows metrics |
+| `name` | Naming | Font names/strings |
+| `cmap` | Character Map | Unicode to glyph mapping |
+| `glyf` | Glyph Data | TrueType outlines |
+| `loca` | Location | Glyph offsets |
+| `CFF ` | CFF | Compact Font Format |
+| `post` | PostScript | PostScript names |
+| `GPOS` | Glyph Positioning | OpenType positioning |
+| `GSUB` | Glyph Substitution | OpenType substitution |
+| `fvar` | Font Variations | Variable font axes |
+| `gvar` | Glyph Variations | Glyph deltas |
+| `COLR` | Color Layers | Color font layers |
+| `CPAL` | Color Palettes | Color font palettes |
+
+## Detailed Documentation
+
+For table access via the Ruby API, see the [SfntFont API](/api/sfnt-font).

data/docs/cli/unicode.md

@@ -0,0 +1,101 @@
+---
+title: unicode
+---
+
+# unicode
+
+Show Unicode coverage and character mappings.
+
+## Quick Reference
+
+```bash
+fontisan unicode <font> [options]
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--format FORMAT` | Output format (text, yaml, json) |
+| `--ranges` | Show Unicode ranges |
+| `--scripts` | Group by script |
+| `--missing` | Show missing from range |
+
+## Output
+
+Shows:
+- Unicode ranges covered
+- Scripts supported
+- Character count per range
+- Cmap table summary
+
+## Examples
+
+```bash
+# Basic Unicode info
+fontisan unicode font.ttf
+
+# Show Unicode ranges
+fontisan unicode font.ttf --ranges
+
+# Group by script
+fontisan unicode font.ttf --scripts
+
+# JSON output
+fontisan unicode font.ttf --format json
+```
+
+## Sample Output
+
+```
+Unicode Coverage
+================
+
+Range                            Characters
+-------------------------------  ----------
+Basic Latin (U+0000-U+007F)     95
+Latin-1 Supplement (U+0080-U+00FF)  96
+Latin Extended-A (U+0100-U+017F)    128
+Latin Extended-B (U+0180-U+024F)    48
+Spacing Modifier Letters (U+02B0-U+02FF) 8
+Greek and Coptic (U+0370-U+03FF)    72
+Cyrillic (U+0400-U+04FF)            66
+
+Total characters: 513
+```
+
+## Common Unicode Ranges
+
+| Range | Name | Typical Use |
+|-------|------|-------------|
+| U+0000-U+007F | Basic Latin | ASCII |
+| U+0080-U+00FF | Latin-1 Supplement | Western European |
+| U+0100-U+017F | Latin Extended-A | European |
+| U+0400-U+04FF | Cyrillic | Russian, etc. |
+| U+0590-U+05FF | Hebrew | Hebrew |
+| U+0600-U+06FF | Arabic | Arabic |
+| U+0900-U+097F | Devanagari | Hindi, etc. |
+| U+4E00-U+9FFF | CJK Unified | Chinese/Japanese |
+| U+AC00-U+D7AF | Hangul | Korean |
+
+## Use Cases
+
+### Check Script Support
+
+```bash
+fontisan unicode font.ttf --scripts | grep -i cyrillic
+```
+
+### Find Coverage Gaps
+
+```bash
+fontisan unicode font.ttf --missing
+```
+
+### Compare Fonts
+
+```bash
+fontisan unicode font1.ttf --format json > unicode1.json
+fontisan unicode font2.ttf --format json > unicode2.json
+diff <(jq . unicode1.json) <(jq . unicode2.json)
+```

data/docs/cli/validate.md

@@ -0,0 +1,48 @@
+---
+title: validate
+---
+
+# validate
+
+Validate fonts against industry-standard profiles.
+
+## Quick Reference
+
+```bash
+fontisan validate <font> --profile <profile> [options]
+```
+
+## Validation Profiles
+
+| Profile | Description |
+|---------|-------------|
+| `opentype` | OpenType specification compliance |
+| `google_fonts` | Google Fonts requirements |
+| `microsoft` | Microsoft font standards |
+| `adobe` | Adobe font guidelines |
+| `production` | Production-ready validation |
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--profile NAME` | Validation profile to use |
+| `--format FORMAT` | Output format (text, yaml, json) |
+| `--verbose` | Show all checks and results |
+
+## Examples
+
+```bash
+# Validate for Google Fonts
+fontisan validate font.ttf --profile google_fonts
+
+# Validate for production
+fontisan validate font.ttf --profile production
+
+# JSON output
+fontisan validate font.ttf --profile opentype --format json
+```
+
+## Detailed Documentation
+
+For comprehensive documentation including profile details and validation helpers, see the [validate command guide](/guide/cli/validate).

data/docs/cli/variable.md

@@ -0,0 +1,126 @@
+---
+title: variable
+---
+
+# variable
+
+Inspect variable font axes and named instances.
+
+## Quick Reference
+
+```bash
+fontisan variable <font> [options]
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--format FORMAT` | Output format (text, yaml, json) |
+| `--instances` | Show named instances |
+| `--axes` | Show axes only |
+
+## Output
+
+Shows:
+- Variation axes with ranges and defaults
+- Named instances (presets)
+- Axis flags (hidden, etc.)
+
+## Examples
+
+```bash
+# Full variable font info
+fontisan variable VariableFont.ttf
+
+# Show only axes
+fontisan variable VariableFont.ttf --axes
+
+# Show named instances
+fontisan variable VariableFont.ttf --instances
+
+# JSON output for processing
+fontisan variable VariableFont.ttf --format json
+```
+
+## Sample Output
+
+```
+Variable Font: VariableFont.ttf
+================================
+
+Axes (2)
+--------
+Tag     Name          Min      Default  Max      Flags
+------  -----------   -----    -------  -----    -----
+wght    Weight        100      400      900      -
+wdth    Width         75%      100%     125%     -
+
+Named Instances (6)
+-------------------
+Name                  Coordinates
+------------------    --------------------
+Thin                  wght:100
+Light                 wght:300
+Regular               wght:400
+Medium                wght:500
+Bold                  wght:700
+Black                 wght:900
+```
+
+## Understanding Axes
+
+### Standard Axes
+
+| Tag | Name | Typical Range | Description |
+|-----|------|---------------|-------------|
+| `wght` | Weight | 1-999 | Font weight (thin to black) |
+| `wdth` | Width | 50-200 | Width percentage |
+| `slnt` | Slant | -90 to +90 | Slant angle in degrees |
+| `ital` | Italic | 0-1 | Italic toggle |
+| `opsz` | Optical Size | 8-144 | Point size for optical sizing |
+
+### Registered Axes
+
+| Tag | Name | Description |
+|-----|------|-------------|
+| `GRAD` | Grade | Weight change without width change |
+| `XTRA` | X-tra | X-height adjustment |
+| `XOPQ` | X-opaque | Horizontal stroke adjustment |
+| `YOPQ` | Y-opaque | Vertical stroke adjustment |
+| `YTRA` | Y-tra | Y-height adjustment |
+| `YTLC` | Y-lowercase | Lowercase height |
+| `YTUC` | Y-uppercase | Uppercase height |
+| `YTAS` | Y-ascender | Ascender height |
+| `YTDE` | Y-descender | Descender depth |
+| `YTFI` | Y-figure | Figure height |
+
+## Use Cases
+
+### Discover Available Instances
+
+```bash
+fontisan variable font.ttf --instances
+```
+
+### Get Axis Range for Instance Generation
+
+```bash
+# Get weight range
+fontisan variable font.ttf --format json | jq '.axes[] | select(.tag=="wght")'
+```
+
+### Check if Font is Variable
+
+```bash
+if fontisan variable font.ttf 2>/dev/null; then
+  echo "Variable font"
+else
+  echo "Static font"
+fi
+```
+
+## Related Commands
+
+- [instance](/cli/instance) — Generate static instances
+- [info](/cli/info) — Get font information