fontisan 0.2.13 → 0.2.16

data/docs/cli/dump-table.md

@@ -0,0 +1,110 @@
+---
+title: dump-table
+---
+
+# dump-table
+
+Extract raw table data from a font.
+
+## Quick Reference
+
+```bash
+fontisan dump-table <font> <table-tag> [options]
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--output FILE` | Output file (default: stdout) |
+| `--hex` | Output as hexadecimal |
+| `--json` | Parse and output as JSON |
+
+## Output
+
+Outputs raw binary table data, or parsed data if `--json` is specified.
+
+## Examples
+
+### Raw Binary Output
+
+```bash
+# Dump head table to file
+fontisan dump-table font.ttf head --output head.bin
+
+# Dump cmap table
+fontisan dump-table font.ttf cmap --output cmap.bin
+```
+
+### Hexadecimal Output
+
+```bash
+# View as hex
+fontisan dump-table font.ttf head --hex
+```
+
+### Parsed JSON Output
+
+```bash
+# Get parsed table data
+fontisan dump-table font.ttf head --json
+
+# Extract specific values
+fontisan dump-table font.ttf head --json | jq '.unitsPerEm'
+```
+
+## Common Tables to Dump
+
+| Table | Contains |
+|-------|----------|
+| `head` | Font header, units per em, bbox |
+| `name` | All naming strings |
+| `cmap` | Character to glyph mapping |
+| `glyf` | Glyph outlines (TrueType) |
+| `CFF ` | Compact font format data |
+| `maxp` | Maximum profile |
+| `hhea` | Horizontal header |
+| `OS/2` | OS/2 metrics |
+| `post` | PostScript names |
+| `GPOS` | Glyph positioning |
+| `GSUB` | Glyph substitution |
+| `fvar` | Variation axes |
+| `STAT` | Style attributes |
+
+## Use Cases
+
+### Debug Font Issues
+
+```bash
+# Check head table values
+fontisan dump-table font.ttf head --json
+```
+
+### Extract Naming Data
+
+```bash
+# Get all name strings
+fontisan dump-table font.ttf name --json > names.json
+```
+
+### Compare Tables Between Fonts
+
+```bash
+# Compare head tables
+diff <(fontisan dump-table font1.ttf head --hex) \
+     <(fontisan dump-table font2.ttf head --hex)
+```
+
+### Backup Table Data
+
+```bash
+# Backup critical tables
+fontisan dump-table font.ttf head --output backup/head.bin
+fontisan dump-table font.ttf name --output backup/name.bin
+fontisan dump-table font.ttf cmap --output backup/cmap.bin
+```
+
+## Related Commands
+
+- [tables](/cli/tables) — List all tables
+- [export](/cli/export) — Export to TTX, SVG, etc.

data/docs/cli/export.md

@@ -0,0 +1,176 @@
+---
+title: export
+---
+
+# export
+
+Export font data to various formats for analysis, debugging, or conversion.
+
+## Quick Reference
+
+```bash
+fontisan export <font> --format <format> [options]
+```
+
+## Export Formats
+
+| Format | Description | Use Case |
+|--------|-------------|----------|
+| `ttx` | XML-based TTX format | Debugging, inspection |
+| `svg` | SVG font | Web graphics |
+| `json` | JSON representation | Data processing |
+| `yaml` | YAML representation | Human-readable output |
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--format FORMAT` | Export format (ttx, svg, json, yaml) |
+| `--output FILE` | Output file path |
+| `--tables LIST` | Export specific tables only (comma-separated) |
+| `--pretty` | Pretty-print output (JSON, YAML) |
+| `--glyphs` | Include glyph outlines (SVG) |
+
+## Examples
+
+### Export to TTX
+
+TTX is an XML representation of font tables, useful for debugging and inspection.
+
+```bash
+# Export entire font
+fontisan export font.ttf --format ttx --output font.ttx
+
+# Export specific tables
+fontisan export font.ttf --format ttx --tables head,name,cmap --output partial.ttx
+
+# Export single table
+fontisan export font.ttf --format ttx --tables glyf --output glyf.ttx
+```
+
+### Export to SVG
+
+```bash
+# Export as SVG font
+fontisan export font.ttf --format svg --output font.svg
+
+# Include all glyphs
+fontisan export font.ttf --format svg --glyphs --output font-glyphs.svg
+```
+
+### Export to JSON/YAML
+
+```bash
+# JSON output
+fontisan export font.ttf --format json --output font.json
+
+# Pretty-printed JSON
+fontisan export font.ttf --format json --pretty --output font-pretty.json
+
+# YAML output
+fontisan export font.ttf --format yaml --output font.yaml
+```
+
+## TTX Format
+
+TTX is Adobe's XML format for font tables. It's human-readable and diffable.
+
+### Sample TTX Output
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ttFont sfntVersion="OTTO" ttLibVersion="4.0">
+  <head>
+    <tableVersion value="1.0"/>
+    <fontRevision value="3.046"/>
+    <checkSumAdjustment value="0"/>
+    <unitsPerEm value="1000"/>
+    ...
+  </head>
+  <name>
+    <namerecord nameID="1" platformID="3" platEncID="1" langID="0x409">
+      Source Sans 3
+    </namerecord>
+    ...
+  </name>
+</ttFont>
+```
+
+## SVG Font Format
+
+SVG fonts define glyphs as SVG paths, usable in web contexts.
+
+### Sample SVG Output
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg">
+  <font id="MyFont" horiz-adv-x="500">
+    <font-face font-family="My Font" units-per-em="1000"/>
+    <glyph unicode="A" d="M100 0 L200 700 L300 0 Z"/>
+    ...
+  </font>
+</svg>
+```
+
+## JSON/YAML Output
+
+Structured output for programmatic access.
+
+### Sample JSON Output
+
+```json
+{
+  "format": "OpenType",
+  "family": "Source Sans 3",
+  "style": "Regular",
+  "version": "3.046",
+  "glyphs": 1024,
+  "tables": {
+    "head": { "unitsPerEm": 1000, ... },
+    "name": { "records": [...] },
+    ...
+  }
+}
+```
+
+## Use Cases
+
+### Debug Font Issues
+
+```bash
+# Export and search for issues
+fontisan export font.ttf --format ttx --output debug.ttx
+grep -i "error\|warning" debug.ttx
+```
+
+### Compare Fonts
+
+```bash
+# Export both fonts
+fontisan export font1.ttf --format ttx --output font1.ttx
+fontisan export font2.ttf --format ttx --output font2.ttx
+
+# Compare
+diff font1.ttx font2.ttx
+```
+
+### Extract Font Data
+
+```bash
+# Get font metadata as JSON
+fontisan export font.ttf --format json | jq '.family, .style, .version'
+```
+
+### Create SVG Glyphs
+
+```bash
+# Export individual glyphs for web use
+fontisan export font.ttf --format svg --glyphs --output glyphs.svg
+```
+
+## Related Commands
+
+- [tables](/cli/tables) — List font tables
+- [dump-table](/cli/dump-table) — Extract raw table data
+- [convert](/cli/convert) — Convert font formats

data/docs/cli/features.md

@@ -0,0 +1,124 @@
+---
+title: features
+---
+
+# features
+
+List OpenType features in a font.
+
+## Quick Reference
+
+```bash
+fontisan features <font> [options]
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--format FORMAT` | Output format (text, yaml, json) |
+| `--script TAG` | Filter by script |
+| `--language TAG` | Filter by language |
+| `--detail` | Show feature details |
+
+## Output
+
+Shows:
+- Feature tags
+- Feature names/descriptions
+- Scripts that use each feature
+- Lookup count
+
+## Examples
+
+```bash
+# List all features
+fontisan features font.ttf
+
+# Features for specific script
+fontisan features font.ttf --script latn
+
+# With details
+fontisan features font.ttf --detail
+
+# JSON output
+fontisan features font.ttf --format json
+```
+
+## Sample Output
+
+```
+OpenType Features
+=================
+
+Tag     Name                    Scripts    Lookups
+------  ----------------------  ---------  -------
+liga    Standard Ligatures      latn,cyrl  12
+dlig    Discretionary Ligatures latn       4
+kern    Kerning                 all        156
+mark    Mark Positioning        all        48
+mkmk    Mark to Mark            all        24
+onum    Oldstyle Figures        latn       1
+pnum    Proportional Figures    latn       1
+tnum    Tabular Figures         latn       1
+zero    Slashed Zero            latn       1
+
+Total: 9 features
+```
+
+## Common Feature Tags
+
+### GSUB (Substitution) Features
+
+| Tag | Name | Description |
+|-----|------|-------------|
+| `liga` | Standard Ligatures | fi, fl, etc. |
+| `dlig` | Discretionary Ligatures | Optional ligatures |
+| `hlig` | Historical Ligatures | Archaic forms |
+| `calt` | Contextual Alternates | Context-based |
+| `salt` | Stylistic Alternates | Alternate glyphs |
+| `ss01`-`ss20` | Stylistic Sets | Grouped alternates |
+| `smcp` | Small Capitals | Lowercase to small caps |
+| `c2sc` | Caps to Small Caps | Uppercase to small caps |
+| `onum` | Oldstyle Figures | Varying height |
+| `lnum` | Lining Figures | Uniform height |
+| `pnum` | Proportional Figures | Varying width |
+| `tnum` | Tabular Figures | Uniform width |
+| `zero` | Slashed Zero | Distinguish 0/O |
+| `case` | Case-Sensitive Forms | Uppercase adjustment |
+
+### GPOS (Positioning) Features
+
+| Tag | Name | Description |
+|-----|------|-------------|
+| `kern` | Kerning | Pair adjustments |
+| `mark` | Mark Positioning | Diacritics |
+| `mkmk` | Mark to Mark | Stacked diacritics |
+| `dist` | Distances | Spacing |
+| `abvm` | Above Marks | Positioning above |
+| `blwm` | Below Marks | Positioning below |
+
+## Use Cases
+
+### Check for Ligatures
+
+```bash
+fontisan features font.ttf | grep liga
+```
+
+### Check for Small Caps
+
+```bash
+fontisan features font.ttf | grep -E "smcp|c2sc"
+```
+
+### Compare Feature Sets
+
+```bash
+diff <(fontisan features font1.ttf) <(fontisan features font2.ttf)
+```
+
+## Related Commands
+
+- [scripts](/cli/scripts) — List supported scripts
+- [info](/cli/info) — Get comprehensive font info

data/docs/cli/glyphs.md

@@ -0,0 +1,90 @@
+---
+title: glyphs
+---
+
+# glyphs
+
+List and inspect glyphs in a font.
+
+## Quick Reference
+
+```bash
+fontisan glyphs <font> [options]
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--format FORMAT` | Output format (text, yaml, json) |
+| `--with-unicode` | Include Unicode codepoints |
+| `--with-bbox` | Include bounding boxes |
+| `--filter PATTERN` | Filter by glyph name pattern |
+
+## Output
+
+Lists all glyphs with:
+- Glyph ID (GID)
+- Glyph name
+- Unicode codepoint (if mapped)
+- Bounding box (optional)
+
+## Examples
+
+```bash
+# List all glyphs
+fontisan glyphs font.ttf
+
+# With Unicode codepoints
+fontisan glyphs font.ttf --with-unicode
+
+# With bounding boxes
+fontisan glyphs font.ttf --with-bbox
+
+# Filter by name pattern
+fontisan glyphs font.ttf --filter "uni*"
+
+# JSON output for processing
+fontisan glyphs font.ttf --format json > glyphs.json
+```
+
+## Sample Output
+
+```
+GID   Name              Unicode    Bounding Box
+----  ----------------  ---------  ---------------
+0     .notdef           -          (0, 0, 500, 700)
+1     space             U+0020     (0, 0, 0, 0)
+2     exclam            U+0021     (100, 0, 200, 700)
+3     quotedbl          U+0022     (80, 450, 420, 700)
+4     numbersign        U+0023     (30, 0, 470, 700)
+...
+```
+
+## Use Cases
+
+### Count Glyphs
+
+```bash
+fontisan glyphs font.ttf | wc -l
+```
+
+### Find Specific Glyphs
+
+```bash
+# Find ligatures
+fontisan glyphs font.ttf | grep "_"
+
+# Find small caps
+fontisan glyphs font.ttf | grep "\.sc"
+```
+
+### Export Glyph List
+
+```bash
+fontisan glyphs font.ttf --format json --with-unicode > glyph-map.json
+```
+
+## Detailed Documentation
+
+For glyph access via the Ruby API, see the [GlyphAccessor API](/api/models/glyph-accessor).

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