fontist 2.1.3 → 2.1.4

data/docs/guide/concepts/variable-fonts.md

@@ -0,0 +1,212 @@
+---
+title: Variable Fonts
+---
+
+# Variable Fonts
+
+**Variable Fonts** (OpenType 1.8+) contain multiple styles in a single file through named **axes**. Instead of separate files for each weight, one file can contain all variations.
+
+## Why Variable Fonts?
+
+### Before: Static Fonts
+
+```
+fonts/
+├── Roboto-Thin.ttf        (100)
+├── Roboto-Light.ttf       (300)
+├── Roboto-Regular.ttf     (400)
+├── Roboto-Medium.ttf      (500)
+├── Roboto-Bold.ttf        (700)
+└── Roboto-Black.ttf       (900)
+
+Total: 6 files, ~1.2MB
+```
+
+### After: Variable Font
+
+```
+fonts/
+└── RobotoFlex-VF.ttf
+
+Total: 1 file, ~800KB
+```
+
+---
+
+## Standard Axes
+
+Variable fonts use **axes** to define adjustable properties:
+
+| Axis Tag | Name | Description | Range |
+|----------|------|-------------|-------|
+| `wght` | Weight | Stroke thickness | 100-900 |
+| `wdth` | Width | Horizontal compression | 25%-200% |
+| `slnt` | Slant | Oblique angle | -15° to 0° |
+| `ital` | Italic | Italic variation | 0 or 1 |
+| `opsz` | Optical Size | Size optimization | 8pt-144pt |
+
+### Weight Axis (`wght`)
+
+The most common axis, replacing multiple static weights:
+
+```css
+/* CSS usage */
+font-weight: 400;  /* Regular */
+font-weight: 700;  /* Bold */
+font-weight: 543;  /* Any value in range */
+```
+
+### Width Axis (`wdth`)
+
+Controls horizontal compression/extension:
+
+```css
+font-stretch: 100%;  /* Normal */
+font-stretch: 75%;   /* Condensed */
+font-stretch: 125%;  /* Extended */
+```
+
+### Optical Size Axis (`opsz`)
+
+Optimizes glyphs for different sizes:
+
+```css
+font-optical-sizing: auto;
+/* or manually: */
+font-variation-settings: 'opsz' 12;
+```
+
+---
+
+## Custom Axes
+
+Fonts can define custom axes beyond the standard five:
+
+| Axis Tag | Name | Description |
+|----------|------|-------------|
+| `GRAD` | Grade | Weight change without width adjustment |
+| `XTRA` | X-height | Adjust x-height |
+| `XOPQ` | X Optical | Horizontal stroke adjustment |
+| `YOPQ` | Y Optical | Vertical stroke adjustment |
+| `ROTL` | Rotation | Glyph rotation |
+| `CASL` | Casual | Formal to casual variation |
+
+### Example: Roboto Flex
+
+Roboto Flex is a highly customizable variable font:
+
+```
+RobotoFlex-VF.ttf
+├── wght axis: 100 → 900    (weight)
+├── wdth axis: 25% → 151%   (width)
+├── GRAD axis: -200 → 150   (grade)
+├── XTRA axis: 323 → 608    (x-height)
+├── XOPQ axis: 27 → 175     (x optical)
+├── YOPQ axis: 25 → 135     (y optical)
+├── YTFI axis: 560 → 788    (y-fit)
+├── YTLC axis: 416 → 570    (lowercase)
+├── YTUC axis: 528 → 760    (uppercase)
+└── YTAS axis: 649 → 854    (ascender)
+```
+
+---
+
+## Using Variable Fonts
+
+### In Fontist
+
+```bash
+# Variable fonts install like any other font
+fontist install "Roboto Flex"
+
+# The single VF file replaces multiple static files
+fontist status "Roboto Flex"
+```
+
+### In CSS
+
+```css
+/* Basic usage */
+.element {
+  font-family: "Roboto Flex";
+  font-weight: 450;
+}
+
+/* Advanced control */
+.element {
+  font-variation-settings:
+    'wght' 450,
+    'GRAD' 50,
+    'XTRA' 500;
+}
+```
+
+### In Fontisan
+
+Fontisan provides variable font operations:
+
+- **Instantiate** - Create static instances from variable fonts
+- **Subset axes** - Reduce axis ranges to needed values
+- **Axis analysis** - Report available axes and ranges
+
+```bash
+# Create a static instance at weight 450
+fontisan instantiate RobotoFlex-VF.ttf --wght 450
+
+# Subset to only weight range 400-700
+fontisan subset-axes RobotoFlex-VF.ttf --wght 400-700
+```
+
+---
+
+## Named Instances
+
+Variable fonts can define **named instances** - preset combinations of axis values:
+
+| Instance Name | wght | wdth |
+|--------------|------|------|
+| Light | 300 | 100 |
+| Regular | 400 | 100 |
+| Bold | 700 | 100 |
+| Condensed Bold | 700 | 75 |
+
+These appear as separate fonts in some applications.
+
+---
+
+## Variable Fonts vs Static Fonts
+
+| Aspect | Static | Variable |
+|--------|--------|----------|
+| Files | Multiple | Single |
+| File size | Larger total | Smaller total |
+| Weight options | Fixed set | Continuous |
+| CSS control | Limited | Fine-grained |
+| Browser support | Universal | Modern browsers |
+| PDF embedding | Simple | Requires care |
+
+---
+
+## Detecting Variable Fonts
+
+### Using Fontist
+
+```bash
+fontist status --verbose
+# Shows if installed fonts are variable
+```
+
+### Using Fontisan
+
+```bash
+fontisan analyze font.ttf
+# Reports axes, ranges, and named instances
+```
+
+---
+
+## See Also
+
+- [Fonts & Styles](/guide/concepts/fonts) - Basic font concepts
+- [Formats & Containers](/guide/concepts/formats) - File formats explained
+- [Fontisan Documentation](https://www.fontist.org/fontisan/) - Variable font operations

data/docs/guide/formulas.md

@@ -0,0 +1,192 @@
+---
+title: Formulas
+---
+
+# Formulas
+
+Formulas are YAML files that describe how to download and install fonts. Fontist uses formulas to locate fonts from various sources and install them consistently across platforms.
+
+## How Formulas Work
+
+When you run `fontist install "Fira Code"`, Fontist:
+
+1. Searches the formula repository for a formula matching "Fira Code"
+2. Reads the formula to find the download URL and extraction instructions
+3. Downloads the font archive
+4. Extracts and installs the font files to your Fontist directory
+
+The formula contains all the metadata needed: download URLs, checksums, file patterns, font names, and styles.
+
+## Formula Repository
+
+### Official Repository
+
+The main formula repository is [fontist/formulas](https://github.com/fontist/formulas) on GitHub. It includes formulas for:
+
+- Google Fonts (Roboto, Open Sans, etc.)
+- SIL Fonts
+- macOS system fonts
+- Windows fonts
+- Many other open source fonts
+
+### Local Storage
+
+Fontist clones the formulas repository to your local machine:
+
+```
+~/.fontist/
+└── versions/
+    └── v4/
+        └── formulas/           # Git clone of fontist/formulas
+            └── Formulas/       # YAML formula files
+                ├── roboto.yml
+                ├── open-sans.yml
+                ├── private/    # Custom formula repos
+                │   └── my-org/
+                │       └── custom-font.yml
+                └── ...
+```
+
+### Automatic Management
+
+Fontist manages the formulas repository automatically:
+
+- **Lazy initialization**: The repository is cloned on first use
+- **Automatic updates**: Run `fontist update` to fetch the latest formulas
+- **Shallow clone**: Only the latest commit is downloaded (depth=1) for efficiency
+
+```sh
+# Update to latest formulas
+fontist update
+
+# This pulls the latest changes and rebuilds the index
+```
+
+### Formula Index
+
+For fast lookups, Fontist builds an index mapping font names to formula files:
+
+```
+~/.fontist/versions/v4/
+├── formula_index.default_family.yml    # Font name → formula path
+├── formula_index.preferred_family.yml  # Alternative naming
+└── filename_index.yml                  # Filename → formula path
+```
+
+The index is rebuilt automatically when formulas are updated.
+
+## Viewing Available Formulas
+
+To see all available fonts:
+
+```sh
+fontist list
+```
+
+Search for a specific font:
+
+```sh
+fontist list "Roboto"
+```
+
+The list shows both installed fonts and fonts available in formulas.
+
+## Formula Structure
+
+A formula is a YAML file with this structure:
+
+```yaml
+name: Roboto
+description: Roboto is a neo-grotesque sans-serif typeface family
+homepage: https://fonts.google.com/specimen/Roboto
+resources:
+  Roboto.zip:
+    urls:
+    - https://github.com/googlefonts/Roboto/releases/download/v3.009/Roboto.zip
+    sha256: abc123...
+fonts:
+- name: Roboto
+  styles:
+  - family_name: Roboto
+    type: Regular
+    full_name: Roboto Regular
+    post_script_name: Roboto-Regular
+    filename: Roboto-Regular.ttf
+```
+
+## Creating Custom Formulas
+
+If a font isn't in the main repository, you can create a custom formula:
+
+```sh
+fontist create-formula https://example.com/fonts/myfont.zip
+```
+
+This command:
+
+1. Downloads the font archive
+2. Analyzes the font files
+3. Generates a formula YAML file
+
+You can specify options:
+
+```sh
+fontist create-formula https://example.com/fonts/myfont.zip \
+  --name "My Font" \
+  --subdir "fonts/otf" \
+  --file-pattern "*.otf"
+```
+
+### Custom Formula Use Cases
+
+- **Private fonts**: Create formulas for proprietary fonts your organization uses
+- **New fonts**: Add support for fonts not yet in the main repository
+- **Contributing**: Prepare formulas for submission to the Fontist project
+
+## Private Formula Repositories
+
+Organizations can maintain private formula repositories for internal or licensed fonts.
+
+### Adding a Private Repository
+
+```sh
+# Add a private formula repository
+fontist repo add my-company https://github.com/mycompany/fontist-formulas
+
+# List configured repositories
+fontist repo list
+
+# Update a specific repository
+fontist repo update my-company
+
+# Remove a repository
+fontist repo remove my-company
+```
+
+### Private Repository Structure
+
+Private repos are stored alongside the main formulas:
+
+```
+~/.fontist/versions/v4/formulas/Formulas/private/
+├── my-company/
+│   ├── corporate-font.yml
+│   └── licensed-font.yml
+└── another-org/
+    └── special-font.yml
+```
+
+### When to Use Private Repositories
+
+- **Licensed fonts**: Fonts your organization has licensed for internal use
+- **Custom fonts**: Proprietary typefaces developed in-house
+- **Preliminary formulas**: Testing formulas before contributing to the main repo
+
+See the [repo command reference](/cli/repo) for complete command documentation.
+
+## Related
+
+- [How Fontist Works](/guide/how-it-works) - Internal architecture and indexes
+- [create-formula CLI reference](/cli/create-formula) - Command options and examples
+- [repo CLI reference](/cli/repo) - Managing formula repositories
+- [update CLI reference](/cli/update) - Updating formulas