fontist 2.1.3 → 2.1.4

data/docs/api/manifest.md

@@ -0,0 +1,209 @@
+---
+title: Fontist::Manifest
+---
+
+# Fontist::Manifest
+
+The `Fontist::Manifest` interface allows you to work with multiple fonts at once using a manifest format.
+
+## Overview
+
+Manifests are useful when you need to:
+- Find locations of multiple fonts in one operation
+- Install multiple fonts from a single definition
+- Integrate with build systems or configuration files
+
+## Global Options
+
+Fontist can be switched to use preferred family names. This format was used prior to v1.10.
+
+```ruby
+Fontist.preferred_family = true
+```
+
+## Manifest Format
+
+The manifest format is a Hash (or YAML) with font names as keys and an array of styles as values:
+
+```ruby
+{
+  "Segoe UI" => ["Regular", "Bold"],
+  "Roboto Mono" => ["Regular"]
+}
+```
+
+## Class Methods
+
+### `.from_yaml(yaml_string)`
+
+Create a manifest from a YAML string.
+
+**Parameters:**
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `yaml_string` | String | YAML formatted manifest content |
+
+**Returns:** `Fontist::Manifest` — Manifest object
+
+**Example:**
+
+```ruby
+yaml = <<~YAML
+  Segoe UI:
+    - Regular
+    - Bold
+  Roboto Mono:
+    - Regular
+YAML
+
+manifest = Fontist::Manifest.from_yaml(yaml)
+```
+
+---
+
+### `.from_hash(hash)`
+
+Create a manifest from a Hash.
+
+**Parameters:**
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `hash` | Hash | Manifest hash with font names and styles |
+
+**Returns:** `Fontist::Manifest` — Manifest object
+
+**Example:**
+
+```ruby
+manifest = Fontist::Manifest.from_hash({
+  "Segoe UI" => ["Regular", "Bold"],
+  "Roboto Mono" => ["Regular"]
+})
+```
+
+---
+
+### `.from_file(path)`
+
+Create a manifest from a YAML file.
+
+**Parameters:**
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `path` | String | Path to the YAML manifest file |
+
+**Returns:** `Fontist::Manifest` — Manifest object
+
+**Example:**
+
+Given a `manifest.yml` file:
+
+```yaml
+---
+Segoe UI:
+  - Regular
+  - Bold
+Roboto Mono:
+  - Regular
+```
+
+```ruby
+manifest = Fontist::Manifest.from_file("manifest.yml")
+```
+
+## Instance Methods
+
+### `.locations`
+
+Get font locations from the manifest.
+
+**Returns:** `Hash` — Nested hash with font paths and names
+
+**Example:**
+
+```ruby
+manifest = Fontist::Manifest.from_hash({
+  "Segoe UI" => ["Regular", "Bold"]
+})
+locations = manifest.locations
+
+# Returns:
+# {
+#   "Segoe UI" => {
+#     "Regular" => {
+#       "full_name" => "Segoe UI",
+#       "paths" => ["/Users/user/.fontist/fonts/SEGOEUI.TTF"]
+#     },
+#     "Bold" => {
+#       "full_name" => "Segoe UI Bold",
+#       "paths" => ["/Users/user/.fontist/fonts/SEGOEUIB.TTF"]
+#     }
+#   }
+# }
+```
+
+---
+
+### `.install(confirmation: "no")`
+
+Install fonts from the manifest and return their locations.
+
+**Parameters:**
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `confirmation` | String | License confirmation, use `"yes"` to accept license |
+
+**Returns:** `Hash` — Nested hash with font paths and names
+
+**Example:**
+
+```ruby
+manifest = Fontist::Manifest.from_file("manifest.yml")
+locations = manifest.install(confirmation: "yes")
+
+# Returns installed font locations:
+# {
+#   "Segoe UI" => {
+#     "Regular" => {
+#       "full_name" => "Segoe UI",
+#       "paths" => ["/Users/user/.fontist/fonts/SEGOEUI.TTF"]
+#     },
+#     "Bold" => {
+#       "full_name" => "Segoe UI Bold",
+#       "paths" => ["/Users/user/.fontist/fonts/SEGOEUIB.TTF"]
+#     }
+#   },
+#   "Roboto Mono" => {
+#     "Regular" => {
+#       "full_name" => "Roboto Mono Regular",
+#       "paths" => ["/Users/user/.fontist/fonts/RobotoMono-VariableFont_wght.ttf"]
+#     }
+#   }
+# }
+```
+
+## Return Value Structure
+
+The return value from `locations` or `install` is a nested Hash:
+
+```ruby
+{
+  "Font Name" => {
+    "Style Name" => {
+      "full_name" => "Full Font Name",  # String or nil if not found
+      "paths" => ["/path/to/font.ttf"]   # Array of paths, empty if not found
+    }
+  }
+}
+```
+
+The `full_name` field is useful to choose a specific font in a font collection file (TTC).
+
+## See Also
+
+- [Fontist::Font](/api/font) — Individual font installation
+- [Fontist::Formula](/api/formula) — Formula information

data/docs/cli/cache.md

@@ -0,0 +1,100 @@
+# fontist cache
+
+Manage Fontist cache directories.
+
+## Subcommands
+
+| Command | Description |
+|---------|-------------|
+| [`fontist cache clear`](#cache-clear) | Clear font download cache |
+| [`fontist cache clear-import`](#cache-clear-import) | Clear import cache |
+| [`fontist cache info`](#cache-info) | Show cache information |
+
+---
+
+## cache clear
+
+Clear the font download cache.
+
+### Syntax
+
+```sh
+fontist cache clear
+```
+
+### Description
+
+Removes:
+- Downloaded font archives
+- System font indexes
+
+This does not remove installed fonts, only cached downloads.
+
+### Examples
+
+```sh
+fontist cache clear
+```
+
+---
+
+## cache clear-import
+
+Clear the import cache used during formula creation.
+
+### Syntax
+
+```sh
+fontist cache clear-import [options]
+```
+
+### Options
+
+| Option | Alias | Type | Description |
+|--------|-------|------|-------------|
+| `--verbose` | `-v` | boolean | Show detailed output |
+
+### Examples
+
+```sh
+fontist cache clear-import
+```
+
+---
+
+## cache info
+
+Show cache information including sizes and file counts.
+
+### Syntax
+
+```sh
+fontist cache info
+```
+
+### Output
+
+- Font download cache location and size
+- Import cache location and size
+- File counts for each cache
+
+### Examples
+
+```sh
+fontist cache info
+```
+
+---
+
+## Cache Locations
+
+| Cache | Default Location |
+|-------|-------------------|
+| Font downloads | `~/.fontist/downloads` |
+| Import cache | `~/.fontist/import_cache` |
+
+## When to Clear Cache
+
+- **Free disk space**: Cache can grow large with many font downloads
+- **Corrupted downloads**: If a download was interrupted or corrupted
+- **After import operations**: Clear import cache after creating formulas

data/docs/cli/config.md

@@ -0,0 +1,123 @@
+# fontist config
+
+Manage Fontist configuration settings.
+
+## Subcommands
+
+| Command | Description |
+|---------|-------------|
+| [`fontist config show`](#config-show) | Show current configuration |
+| [`fontist config set`](#config-set) | Set a configuration value |
+| [`fontist config delete`](#config-delete) | Delete a configuration key |
+| [`fontist config keys`](#config-keys) | List available configuration keys |
+
+---
+
+## config show
+
+Show values of the current configuration.
+
+### Syntax
+
+```sh
+fontist config show
+```
+
+### Examples
+
+```sh
+fontist config show
+```
+
+---
+
+## config set
+
+Set a configuration key to a value.
+
+### Syntax
+
+```sh
+fontist config set KEY VALUE
+```
+
+### Arguments
+
+| Name | Required | Description |
+|------|----------|-------------|
+| `KEY` | Yes | Configuration key name |
+| `VALUE` | Yes | Value to set |
+
+### Examples
+
+```sh
+# Set custom fonts path
+fontist config set fonts_path /var/myfonts
+
+# Set timeout
+fontist config set open_timeout 120
+```
+
+---
+
+## config delete
+
+Delete a configuration key (resets to default).
+
+### Syntax
+
+```sh
+fontist config delete KEY
+```
+
+### Arguments
+
+| Name | Required | Description |
+|------|----------|-------------|
+| `KEY` | Yes | Configuration key to delete |
+
+### Examples
+
+```sh
+fontist config delete fonts_path
+```
+
+---
+
+## config keys
+
+List all available configuration keys with their default values.
+
+### Syntax
+
+```sh
+fontist config keys
+```
+
+### Examples
+
+```sh
+fontist config keys
+```
+
+Output:
+```
+Available keys:
+fonts_path (default: /home/user/.fontist/fonts)
+open_timeout (default: 60)
+read_timeout (default: 60)
+```
+
+---
+
+## Available Configuration Keys
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `fonts_path` | `~/.fontist/fonts` | Where Fontist installs fonts |
+| `open_timeout` | 60 | HTTP open timeout in seconds |
+| `read_timeout` | 60 | HTTP read timeout in seconds |
+
+## Configuration File
+
+Configuration is stored in `~/.fontist/config.yml`.

data/docs/cli/create-formula.md

@@ -0,0 +1,65 @@
+# fontist create-formula
+
+Create a new Fontist formula from a font download URL.
+
+## Syntax
+
+```sh
+fontist create-formula URL [options]
+```
+
+## Arguments
+
+| Name | Required | Description |
+|------|----------|-------------|
+| `URL` | Yes | URL to download fonts from |
+
+## Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `--name` | string | Font name (e.g., "Times New Roman") |
+| `--mirror` | array | Mirror URLs (can be repeated) |
+| `--subdir` | string | Subdirectory to extract fonts from |
+| `--file-pattern` | string | File pattern to match (e.g., "*.otf") |
+| `--name-prefix` | string | Prefix for font family names |
+
+## Examples
+
+```sh
+# Create formula from a font archive
+fontist create-formula https://example.com/fonts/myfont.zip
+
+# Specify font name
+fontist create-formula https://example.com/fonts/myfont.zip --name "My Font"
+
+# Use subdirectory
+fontist create-formula https://example.com/fonts/myfont.zip --subdir "fonts/otf"
+
+# Filter by file pattern
+fontist create-formula https://example.com/fonts/myfont.zip --file-pattern "*.otf"
+
+# Add mirror URLs
+fontist create-formula https://example.com/fonts/myfont.zip --mirror https://mirror.example.com/fonts/myfont.zip
+```
+
+## How It Works
+
+1. Downloads the font archive from the URL
+2. Extracts and analyzes font files
+3. Detects font names, styles, and metadata
+4. Generates a formula YAML file
+
+## Generated Formula
+
+The formula is saved to `./Formulas/` directory with a filename based on the font name.
+
+## Use Cases
+
+- **New fonts**: Create formulas for fonts not in Fontist
+- **Private fonts**: Create formulas for proprietary fonts
+- **Contributing**: Prepare formulas for submission to Fontist
+
+## Related
+
+- [Create a Formula Guide](https://www.fontist.org/formulas/guide/create-formula) - Detailed formula creation guide

data/docs/cli/exit-codes.md

@@ -0,0 +1,73 @@
+# Exit Codes
+
+Fontist uses standard exit codes to indicate the result of command execution.
+
+| Code | Name | Description |
+|------|------|-------------|
+| 0 | SUCCESS | Command completed successfully |
+| 1 | UNKNOWN_ERROR | Unknown or unexpected error |
+| 2 | NON_SUPPORTED_FONT_ERROR | Font is not supported by fontist |
+| 3 | MISSING_FONT_ERROR | Font could not be found on the system or in formulas |
+| 4 | LICENSING_ERROR | License agreement required but not accepted |
+| 5 | MANIFEST_COULD_NOT_BE_FOUND_ERROR | Manifest file not found at specified path |
+| 6 | MANIFEST_COULD_NOT_BE_READ_ERROR | Manifest file could not be read (invalid YAML or permissions) |
+| 7 | FONT_INDEX_CORRUPTED | Font index file is corrupted and needs to be rebuilt |
+| 8 | REPO_NOT_FOUND | Repository not found |
+| 9 | MAIN_REPO_NOT_FOUND | Main formulas repository not found |
+| 10 | REPO_COULD_NOT_BE_UPDATED | Repository could not be updated (network or git error) |
+| 11 | MANUAL_FONT_ERROR | Manual font installation required (font cannot be downloaded) |
+| 12 | SIZE_LIMIT_ERROR | Formula exceeds size limit. Use --size-limit, --newest, or --smallest options |
+| 13 | FORMULA_NOT_FOUND | Formula not found for the requested font |
+| 14 | FONTCONFIG_NOT_FOUND | Fontconfig is not installed or not found |
+| 15 | FONTCONFIG_FILE_NOT_FOUND | Fontconfig configuration file not found |
+| 16 | INVALID_CONFIG_ATTRIBUTE | Invalid configuration attribute specified |
+
+## Using Exit Codes in Scripts
+
+Exit codes are useful for scripting and CI/CD:
+
+```sh
+#!/bin/bash
+fontist install "Roboto"
+if [ $? -eq 4 ]; then
+  echo "License acceptance required"
+  fontist install "Roboto" --accept-all-licenses
+fi
+```
+
+## Common Patterns
+
+### CI/CD Pipelines
+
+```yaml
+# GitHub Actions example
+- name: Install fonts
+  run: |
+    fontist install --accept-all-licenses --hide-licenses
+    # Check for missing fonts
+    if [ $? -eq 3 ]; then
+      echo "Some fonts not found"
+      exit 1
+    fi
+```
+
+### Error Handling
+
+```ruby
+# Ruby script example
+result = system("fontist install 'Roboto'")
+case $?.exitstatus
+when 0
+  puts "Success"
+when 3
+  puts "Font not found"
+when 4
+  puts "License needs acceptance"
+else
+  puts "Unknown error"
+end
+```
+
+## Related
+
+- [CLI Reference](/cli/) - All CLI commands

data/docs/cli/fontconfig.md

@@ -0,0 +1,85 @@
+# fontist fontconfig
+
+Manage fontconfig integration for Linux systems.
+
+## Subcommands
+
+| Command | Description |
+|---------|-------------|
+| [`fontist fontconfig update`](#fontconfig-update) | Update fontconfig to use Fontist fonts |
+| [`fontist fontconfig remove`](#fontconfig-remove) | Remove Fontist from fontconfig |
+
+---
+
+## fontconfig update
+
+Update fontconfig configuration to include Fontist-installed fonts.
+
+### Syntax
+
+```sh
+fontist fontconfig update
+```
+
+### Description
+
+Creates or updates a fontconfig configuration file that includes Fontist's font directory. This allows applications using fontconfig to discover and use fonts installed by Fontist.
+
+### Examples
+
+```sh
+fontist fontconfig update
+```
+
+### Requirements
+
+- Fontconfig must be installed on your system
+- Typically used on Linux systems
+
+---
+
+## fontconfig remove
+
+Remove Fontist's fontconfig configuration.
+
+### Syntax
+
+```sh
+fontist fontconfig remove [options]
+```
+
+### Options
+
+| Option | Alias | Type | Description |
+|--------|-------|------|-------------|
+| `--force` | `-f` | boolean | Proceed even if configuration file does not exist |
+
+### Examples
+
+```sh
+# Remove fontconfig integration
+fontist fontconfig remove
+
+# Force removal
+fontist fontconfig remove --force
+```
+
+---
+
+## How It Works
+
+Fontist integrates with fontconfig by creating a configuration file at:
+- `~/.config/fontconfig/99-fontist.conf` (or equivalent on your system)
+
+This configuration adds Fontist's fonts directory to fontconfig's search path.
+
+## When to Use
+
+Use fontconfig integration when:
+- Running Linux applications that rely on fontconfig
+- Applications need to discover fonts through fontconfig rather than direct file paths
+- Working with document rendering systems (LaTeX, etc.)
+
+## Related
+
+- [Fontist with Fontconfig guide](/guide/fontconfig) - Detailed integration guide