fontisan 0.2.14 → 0.2.16

data/docs/cli/convert.md

@@ -0,0 +1,87 @@
+---
+title: convert
+---
+
+# convert
+
+Convert individual fonts between different formats.
+
+::: tip For Collection Formats
+Use [pack/unpack](/cli/pack) to work with TTC, OTC, and dfont collections. The convert command is for individual font files only.
+:::
+
+## Quick Reference
+
+```bash
+fontisan convert <input> --to <format> [options]
+```
+
+## Supported Formats
+
+These are individual font formats that can be converted:
+
+| Format | Read | Write | Description |
+|--------|:----:|:-----:|-------------|
+| TTF | ✅ | ✅ | TrueType (glyf outlines) |
+| OTF | ✅ | ✅ | OpenType (CFF outlines) |
+| WOFF | ✅ | ✅ | Web Open Font Format |
+| WOFF2 | ✅ | ✅ | Web Open Font Format 2 |
+| PFB/PFA | ✅ | — | Adobe Type 1 (read for conversion) |
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--to FORMAT` | Target format (ttf, otf, woff, woff2) |
+| `--output FILE` | Output file path |
+| `--optimize` | Enable outline optimization |
+| `--flatten` | Flatten composite glyphs |
+
+## Common Workflows
+
+### Convert for Web
+
+```bash
+# TTF to WOFF2 (recommended for modern browsers)
+fontisan convert font.ttf --to woff2 --output font.woff2
+
+# OTF to WOFF (broader compatibility)
+fontisan convert font.otf --to woff --output font.woff
+```
+
+### Convert Between Outline Formats
+
+```bash
+# TrueType to OpenType (glyf → CFF)
+fontisan convert font.ttf --to otf --output font.otf
+
+# OpenType to TrueType (CFF → glyf)
+fontisan convert font.otf --to ttf --output font.ttf
+```
+
+### Convert Legacy Type 1 Fonts
+
+```bash
+# Type 1 to OpenType
+fontisan convert font.pfb --to otf --output font.otf
+```
+
+## Working with Collections
+
+Collection formats (TTC, OTC, dfont) contain multiple fonts. To convert fonts from a collection:
+
+```bash
+# Step 1: Extract fonts from collection
+fontisan unpack family.ttc --output-dir ./extracted
+
+# Step 2: Convert each font
+fontisan convert ./extracted/Font-Regular.ttf --to woff2 --output Font-Regular.woff2
+fontisan convert ./extracted/Font-Bold.ttf --to woff2 --output Font-Bold.woff2
+
+# Or extract and convert in one step:
+fontisan unpack family.ttc --output-dir ./web --format woff2
+```
+
+## Detailed Documentation
+
+For comprehensive documentation including curve conversion, hint handling, and advanced options, see the [convert command guide](/guide/cli/convert).

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