fontist 2.1.3 → 2.1.4

data/docs/cli/version.md

@@ -0,0 +1,38 @@
+# fontist version
+
+Show Fontist version and formulas repository information.
+
+## Syntax
+
+```sh
+fontist version
+```
+
+## Description
+
+Displays:
+- Fontist gem version
+- Formulas repository URL
+- Formulas version/branch
+- Last commit hash and date
+
+## Examples
+
+```sh
+fontist version
+```
+
+Output:
+```
+fontist: 2.1.3
+formulas:
+  repo: https://github.com/fontist/formulas
+  version: v1.2.3
+  branch: main
+  commit: abc1234
+  updated: 2024-01-15
+```
+
+## Related Commands
+
+- [fontist update](/cli/update) - Update formulas repository

data/docs/components/CliCommand.vue

@@ -0,0 +1,77 @@
+<script setup>
+import { computed } from 'vue'
+const props = defineProps({
+  command: { type: String, required: true }
+})
+import commands from '../.vitepress/data/cli-commands.json'
+const cmd = computed(() => commands[props.command])
+</script>
+
+<template>
+  <div v-if="cmd" class="cli-command">
+    <p class="description">{{ cmd.description }}</p>
+    <pre class="syntax"><code>{{ cmd.syntax }}</code></pre>
+
+    <h3 v-if="cmd.arguments && cmd.arguments.length">Arguments</h3>
+    <table v-if="cmd.arguments && cmd.arguments.length">
+      <thead><tr><th>Name</th><th>Required</th><th>Description</th></tr></thead>
+      <tbody>
+        <tr v-for="arg in cmd.arguments" :key="arg.name">
+          <td><code>{{ arg.name }}</code></td>
+          <td>{{ arg.required ? 'Yes' : 'No' }}</td>
+          <td>{{ arg.description }}</td>
+        </tr>
+      </tbody>
+    </table>
+
+    <h3 v-if="cmd.options && cmd.options.length">Options</h3>
+    <table v-if="cmd.options && cmd.options.length">
+      <thead><tr><th>Option</th><th>Alias</th><th>Type</th><th>Description</th></tr></thead>
+      <tbody>
+        <tr v-for="opt in cmd.options" :key="opt.name">
+          <td><code>--{{ opt.name }}</code></td>
+          <td><code v-if="opt.alias">-{{ opt.alias }}</code></td>
+          <td>{{ opt.type }}</td>
+          <td>{{ opt.description }}</td>
+        </tr>
+      </tbody>
+    </table>
+
+    <h3 v-if="cmd.examples && cmd.examples.length">Examples</h3>
+    <div v-if="cmd.examples && cmd.examples.length" class="examples">
+      <div v-for="example in cmd.examples" :key="example.command" class="example">
+        <p>{{ example.description }}</p>
+        <pre><code>{{ example.command }}</code></pre>
+      </div>
+    </div>
+
+    <p v-if="cmd.related && cmd.related.length" class="related">
+      <strong>Related:</strong>
+      <span v-for="rel in cmd.related" :key="rel">
+        <a :href="`/cli/${rel}`">{{ rel }}</a>{{ rel !== cmd.related[cmd.related.length-1] ? ', ' : '' }}
+      </span>
+    </p>
+  </div>
+</template>
+
+<style scoped>
+.cli-command .syntax {
+  margin: 1rem 0;
+}
+.example {
+  margin: 0.5rem 0;
+}
+.example p {
+  margin: 0;
+  font-weight: 500;
+}
+.example pre {
+  margin: 0.25rem 0;
+  padding: 0.75rem;
+  background: var(--vp-code-block-bg);
+  border-radius: 4px;
+}
+.related {
+  margin-top: 1.5rem;
+}
+</style>

data/docs/components/CliExamples.vue

@@ -0,0 +1,17 @@
+<script setup>
+import { computed } from 'vue'
+const props = defineProps({
+  command: { type: String, required: true }
+})
+import commands from '../.vitepress/data/cli-commands.json'
+const cmd = computed(() => commands[props.command])
+</script>
+
+<template>
+  <div v-if="cmd && cmd.examples">
+    <div v-for="example in cmd.examples" :key="example.command" class="example">
+      <p>{{ example.description }}</p>
+      <pre><code>{{ example.command }}</code></pre>
+    </div>
+  </div>
+</template>

data/docs/components/CliOptions.vue

@@ -0,0 +1,26 @@
+<script setup>
+import { computed } from 'vue'
+const props = defineProps({
+  command: { type: String, required: true }
+})
+import commands from '../.vitepress/data/cli-commands.json'
+const cmd = computed(() => commands[props.command])
+</script>
+
+<template>
+  <div v-if="cmd">
+    <table>
+      <thead>
+        <tr><th>Option</th><th>Alias</th><th>Type</th><th>Description</th></tr>
+      </thead>
+      <tbody>
+        <tr v-for="opt in cmd.options" :key="opt.name">
+          <td><code>--{{ opt.name }}</code></td>
+          <td><code v-if="opt.alias">-{{ opt.alias }}</code></td>
+          <td>{{ opt.type }}</td>
+          <td>{{ opt.description }}</td>
+        </tr>
+      </tbody>
+    </table>
+  </div>
+</template>

data/docs/components/ExitCodes.vue

@@ -0,0 +1,18 @@
+<script setup>
+import exitCodes from '../.vitepress/data/exit-codes.json'
+</script>
+
+<template>
+  <table>
+    <thead>
+      <tr><th>Code</th><th>Name</th><th>Description</th></tr>
+    </thead>
+    <tbody>
+      <tr v-for="code in exitCodes.codes" :key="code.code">
+        <td><code>{{ code.code }}</code></td>
+        <td>{{ code.name }}</td>
+        <td>{{ code.description }}</td>
+      </tr>
+    </tbody>
+  </table>
+</template>

data/docs/guide/ci.md

@@ -1,3 +1,7 @@
+---
+title: CI/CD Integration
+---
+
 # Using Fontist in CI
 
 Fontist works well in CI environments too! You can just `gem install fontist` like normal to get up and running. Hoever, if you don't like waiting for it to compile the native Ruby extensions each time you `gem install fontist` then you might be interested in our premade custom CI helpers.

data/docs/guide/concepts/fonts.md

@@ -0,0 +1,158 @@
+---
+title: Fonts, Styles & Weights
+---
+
+# Fonts, Styles & Weights
+
+Understanding the relationship between font families, styles, and weights is fundamental to working with Fontist.
+
+## Font Family
+
+A **Font Family** is a collection of related fonts that share a common design. When you ask Fontist to install "Open Sans", you're requesting a font family.
+
+```
+Open Sans (Family)
+├── Open Sans Regular
+├── Open Sans Bold
+├── Open Sans Italic
+└── Open Sans Bold Italic
+```
+
+### In Fontist
+
+```bash
+# Install a font family
+fontist install "Open Sans"
+
+# List fonts in a family
+fontist list "Open Sans"
+```
+
+### In Fontisan
+
+Fontisan processes entire font families, providing:
+- Format conversion for all styles
+- Subsetting across the family
+- Validation of family consistency
+
+---
+
+## Font Style
+
+A **Font Style** is a specific variation within a font family, typically defined by weight and italic/roman distinction.
+
+### Common Styles
+
+| Style | Weight | Italic |
+|-------|--------|--------|
+| Regular (Roman) | 400 | No |
+| Italic | 400 | Yes |
+| Bold | 700 | No |
+| Bold Italic | 700 | Yes |
+| Light | 300 | No |
+| Medium | 500 | No |
+| Black | 900 | No |
+
+### Style Naming Conventions
+
+Fonts use various naming conventions:
+
+```
+Full Name:      "Open Sans Bold Italic"
+Family Name:    "Open Sans"
+Style:          "Bold Italic"
+PostScript Name: "OpenSans-BoldItalic"
+```
+
+### In Fontist
+
+```bash
+# Install specific styles (via manifest)
+fontist manifest-install fonts.yml
+```
+
+```yaml
+# fonts.yml
+Open Sans:
+  - Bold
+  - Italic
+```
+
+---
+
+## Font Weight
+
+**Font Weight** is a numeric value representing the thickness of characters. The CSS/OpenType standard defines 9 weight values:
+
+| Value | Name | Common Use |
+|-------|------|------------|
+| 100 | Thin | Headlines |
+| 200 | Extra Light | Display |
+| 300 | Light | Body text (large) |
+| 400 | Regular/Normal | Body text |
+| 500 | Medium | Emphasis |
+| 600 | Semi Bold | Subheadings |
+| 700 | Bold | Strong emphasis |
+| 800 | Extra Bold | Headlines |
+| 900 | Black | Display |
+
+### Weight in Fontist Manifests
+
+```yaml
+# Request by style name
+Roboto:
+  - Bold      # Weight 700
+  - Medium    # Weight 500
+
+# Fontist returns paths to these specific weights
+```
+
+### Weight vs Variable Fonts
+
+With static fonts, each weight is a separate file:
+
+```
+Roboto-Regular.ttf    (weight 400)
+Roboto-Medium.ttf     (weight 500)
+Roboto-Bold.ttf       (weight 700)
+```
+
+With variable fonts, weight becomes a continuous axis:
+
+```
+# Variable font with weight axis 100-900
+RobotoFlex-VF.ttf
+  └── wght axis: 100 → 900 (any value)
+```
+
+See [Variable Fonts](/guide/concepts/variable-fonts) for more details.
+
+---
+
+## Finding Font Names
+
+To use a font with Fontist, you need to know its name:
+
+```bash
+# Search for a font
+fontist list "Segoe"
+
+# Check if a font is installed
+fontist status "Open Sans"
+```
+
+### Name Matching
+
+Fontist matches names flexibly:
+- `"Open Sans"` matches the family
+- `"Open Sans Bold"` matches a specific style
+- `"OpenSans-Bold"` matches PostScript name
+
+---
+
+## See Also
+
+- [Variable Fonts](/guide/concepts/variable-fonts) - Continuous weight and style axes
+- [Formats & Containers](/guide/concepts/formats) - File formats explained
+- [Requirements](/guide/concepts/requirements) - Specifying fonts in manifests
+- [Manifests Guide](/guide/manifests) - Working with font manifests

data/docs/guide/concepts/formats.md

@@ -0,0 +1,234 @@
+---
+title: Formats & Containers
+---
+
+# Formats & Containers
+
+Understanding font file formats and containers helps you work with fonts across different platforms and use cases.
+
+## Font Formats
+
+**Font Format** refers to the internal structure of the font file. Different formats have different capabilities.
+
+### Comparison Table
+
+| Format | Extension | Outlines | Features | Variable | Notes |
+|--------|-----------|----------|----------|----------|-------|
+| TrueType | `.ttf` | Quadratic Bézier | Full | Yes | Most common |
+| OpenType (TT) | `.otf`, `.ttf` | Quadratic | Full | Yes | TrueType outlines |
+| OpenType (CFF) | `.otf` | Cubic Bézier | Full | Yes (CFF2) | PostScript outlines |
+| PostScript Type 1 | `.pfb`, `.pfa` | Cubic | Limited | No | Legacy, deprecated |
+| WOFF | `.woff` | Any | Full | Yes | Compressed web font |
+| WOFF2 | `.woff2` | Any | Full | Yes | Better compression |
+
+### Outline Types
+
+#### TrueType (Quadratic Bézier)
+
+```
+Points connected by quadratic curves
+- Simpler math
+- Faster rendering (historically)
+- More points needed for complex curves
+```
+
+#### CFF/PostScript (Cubic Bézier)
+
+```
+Points connected by cubic curves
+- More elegant curves
+- Fewer points needed
+- Professional typography standard
+```
+
+### OpenType Features
+
+Modern fonts (TTF and OTF) support OpenType features:
+
+```
+OpenType Features:
+├── Glyph substitution (GSUB)
+│   ├── Ligatures (fi, fl → fi, fl)
+│   ├── Small caps
+│   ├── Numerals (lining, old-style, tabular)
+│   └── Stylistic alternates
+├── Glyph positioning (GPOS)
+│   ├── Kerning
+│   ├── Mark positioning
+│   └── Cursor positioning
+└── Layout scripts
+    ├── Latin
+    ├── Arabic
+    ├── Devanagari
+    └── Many more...
+```
+
+---
+
+## Web Font Formats
+
+### WOFF (Web Open Font Format)
+
+- Compressed version of TTF/OTF
+- ~40% smaller than original
+- Supported in all modern browsers
+- Contains same data as source format
+
+### WOFF2
+
+- Next-generation web font format
+- ~30% smaller than WOFF
+- Brotli compression
+- Better for large font families
+
+```bash
+# Convert to WOFF2 with Fontisan
+fontisan convert font.ttf font.woff2
+```
+
+---
+
+## Font Containers
+
+**Font Container** formats can hold multiple fonts in a single file, sharing common data to reduce file size.
+
+### Container Types
+
+| Container | Extension | Contents | Platform |
+|-----------|-----------|----------|----------|
+| TrueType Collection | `.ttc` | Multiple TTF fonts | Cross-platform |
+| OpenType Collection | `.otc` | Multiple OTF fonts | Cross-platform |
+| Data Fork Font | `.dfont` | Multiple fonts | macOS legacy |
+| Font Suitcase | (no extension) | Multiple fonts | Classic Mac OS |
+
+### When Containers Are Used
+
+Containers reduce file size by sharing common tables:
+
+```
+# Separate files (duplicated tables)
+font1.ttf (glyf, head, hmtx, loca...) = 200KB
+font2.ttf (glyf, head, hmtx, loca...) = 200KB
+Total: 400KB
+
+# TTC container (shared tables)
+fonts.ttc (shared: glyf, head...) = 300KB
+Savings: 25%
+```
+
+### Common Container Files
+
+| Font Family | Container | Fonts Included |
+|-------------|-----------|----------------|
+| Segoe UI | segoeui.ttc | Regular, Bold, Italic, Bold Italic |
+| Arial | arial.ttf | Multiple weights |
+| MS Gothic | msgothic.ttc | Regular, Bold |
+
+---
+
+## Working with Containers in Fontist
+
+### Installation
+
+```bash
+# Fontist handles containers automatically
+fontist install "Segoe UI"
+```
+
+### Status Check
+
+```bash
+fontist status "Segoe UI"
+# Returns path to TTC and internal font name
+```
+
+### Ruby API
+
+```ruby
+# Returns container info
+result = Fontist::Font.find("Segoe UI")
+# => { paths: ["/path/to/segoeui.ttc"], full_name: "Segoe UI" }
+
+# The full_name identifies the font within a TTC
+```
+
+---
+
+## Working with Containers in Fontisan
+
+### Extract from Container
+
+```bash
+# Extract individual font from TTC
+fontisan extract segoeui.ttc --font "Segoe UI Bold" --output bold.ttf
+```
+
+### Create Container
+
+```bash
+# Create TTC from multiple TTFs
+fontisan create-ttf regular.ttf bold.ttf italic.ttf --output family.ttc
+```
+
+---
+
+## Format Conversion
+
+### TTF ↔ OTF
+
+```bash
+# Convert TTF to OTF (changes outline type)
+fontisan convert input.ttf output.otf
+
+# Note: Outline conversion may affect rendering
+```
+
+### Desktop ↔ Web
+
+```bash
+# Create web fonts from desktop fonts
+fontisan convert font.ttf font.woff
+fontisan convert font.ttf font.woff2
+```
+
+### Lossless Operations
+
+These operations preserve font data:
+- TTF → WOFF → TTF (round-trip)
+- OTF → WOFF2 → OTF (round-trip)
+- Extract from TTC
+
+Lossy operations:
+- TTF → OTF (outline conversion)
+- Subsetting (removes glyphs)
+- Axis reduction (removes variable data)
+
+---
+
+## Platform Considerations
+
+### macOS
+
+- Supports TTF, OTF, TTC, OTC
+- Legacy support for dfont
+- Font Book handles all formats
+
+### Windows
+
+- Supports TTF, OTF, TTC
+- Fonts in `C:\Windows\Fonts`
+- Per-user fonts in AppData
+
+### Linux
+
+- Supports TTF, OTF, TTC
+- Uses fontconfig for discovery
+- Multiple font directories
+
+---
+
+## See Also
+
+- [Fonts & Styles](/guide/concepts/fonts) - Basic font concepts
+- [Variable Fonts](/guide/concepts/variable-fonts) - Modern variable fonts
+- [Fontisan Documentation](https://www.fontist.org/fontisan/) - Format conversion tools

data/docs/guide/concepts/index.md

@@ -0,0 +1,109 @@
+---
+title: Font Concepts Overview
+---
+
+# Font Concepts
+
+Understanding font terminology is essential for working with Fontist effectively. This section explains the core concepts and how they relate to Fontist, Fontisan, and Formulas.
+
+## Core Hierarchy
+
+```
+Font Family (e.g., "Open Sans")
+├── Font Style (e.g., "Regular", "Bold", "Italic")
+│   ├── Font Weight (e.g., 400, 700)
+│   └── Variable Font Axes (e.g., weight, width, slant)
+│       └── Font File (physical file on disk)
+│           ├── Font Format (OTF, TTF, PS)
+│           └── Font Container (TTC, OTC, dfont)
+```
+
+## Topics
+
+### [Fonts & Styles](/guide/concepts/fonts)
+Font families, styles, and weights—the fundamental building blocks.
+
+### [Variable Fonts](/guide/concepts/variable-fonts)
+Modern variable fonts with adjustable axes for weight, width, and more.
+
+### [Formats & Containers](/guide/concepts/formats)
+File formats (TTF, OTF, WOFF) and container formats (TTC, dfont).
+
+### [Licenses](/guide/concepts/licenses)
+Font licensing and how Fontist handles license requirements.
+
+### [Requirements](/guide/concepts/requirements)
+Specifying what fonts your project needs via manifests.
+
+## How Fontist, Fontisan, and Formulas Connect
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                      FONTIST                            │
+├─────────────────────────────────────────────────────────┤
+│  Font Requirements (Manifest)                           │
+│         │                                               │
+│         ▼                                               │
+│  ┌──────────────┐     ┌──────────────┐                  │
+│  │   Formulas   │────▶│   Downloads  │                  │
+│  │ (Recipes)    │     │   & Installs │                  │
+│  └──────────────┘     └──────────────┘                  │
+│         │                    │                          │
+│         ▼                    ▼                          │
+│  ┌──────────────┐     ┌──────────────┐                  │
+│  │ License      │     │ System Index │                  │
+│  │ Management   │     │ (Detection)  │                  │
+│  └──────────────┘     └──────────────┘                  │
+│                              │                          │
+│                              ▼                          │
+│                    Returns Font Paths                   │
+└─────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────┐
+│                      FONTISAN                           │
+├─────────────────────────────────────────────────────────┤
+│  Input: Font files (from Fontist or elsewhere)          │
+│         │                                               │
+│         ▼                                               │
+│  ┌──────────────┐     ┌──────────────┐                  │
+│  │   Convert    │     │    Subset    │                  │
+│  │  TTF↔OTF↔WOFF│     │  Glyphs only │                  │
+│  └──────────────┘     └──────────────┘                  │
+│         │                    │                          │
+│         ▼                    ▼                          │
+│  ┌──────────────┐     ┌──────────────┐                  │
+│  │   Validate   │     │  Instantiate │                  │
+│  │   Check      │     │  Variable→   │                  │
+│  │   Issues     │     │  Static      │                  │
+│  └──────────────┘     └──────────────┘                  │
+│                              │                          │
+│                              ▼                          │
+│                    Output: Processed Fonts              │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Quick Reference
+
+### File Extensions
+
+| Extension | Meaning |
+|-----------|---------|
+| `.ttf` | TrueType Font |
+| `.otf` | OpenType Font |
+| `.ttc` | TrueType Collection |
+| `.otc` | OpenType Collection |
+| `.woff` | Web Open Font Format |
+| `.woff2` | Web Open Font Format 2 |
+| `.dfont` | macOS Data Fork Font |
+| `.pfb` | PostScript Font Binary |
+
+### Common Tasks
+
+| Task | Tool | Command |
+|------|------|---------|
+| Install fonts | Fontist | `fontist install "Font Name"` |
+| Check installed | Fontist | `fontist status "Font Name"` |
+| Define requirements | Fontist | Create manifest.yml |
+| Convert formats | Fontisan | `fontisan convert input.ttf output.woff2` |
+| Subset glyphs | Fontisan | `fontisan subset font.ttf --glyphs "ABCabc"` |
+| Create formula | Fontist | `fontist create-formula font.ttf` |