fontist 2.1.4 → 2.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53b62fd1983ad3739ec4869071a9a3517ead3f581f0cbc04987bd5cc8ac6bdbf
-  data.tar.gz: ce3a64130bfcb4310f3adeeb79c8a62cfe3412f20c1cacb6c68482b11ad60ef6
+  metadata.gz: 0625c7b3933a74de8462f617558b73b8c4a27112e42a4066209dd66f805df21d
+  data.tar.gz: 7fb21a4892763ed22113cec7950af17a6c716d00f3dc8b569a636c3de013a594
 SHA512:
-  metadata.gz: 36addd8934bcbd3a128c6850921cd66739e992ecaae65464c01457509f7b68c410a83a55efbf5698f0ae88b789f9d620ffb17751effcea718b2f876b4531c99d
-  data.tar.gz: 27f7c34fdfbd88460a95d0b3bdb03c34fc1aa4cdbcd2cd835d520e6363b288e5fd5a8417b69227c34fd3bf45f78c86b8b0fd2cf139e13931bfcced52271941f4
+  metadata.gz: 8446fbdb79e95e818298e6ed0f487789299992afc598676f5bd7f376e8c3dbedc267d46ffcf9acf6cf67c5bb66d96d34338677ce7f9818d0c167729e6db1770e
+  data.tar.gz: 9ca12d1d2a163a289fe0ed5cef1bee92f0f5d6e48b3b79c30c9a9eb86da189802fce19c66393736038d925822524357066d91bed1c54699509a5b26b119cac11

data/.gitignore

@@ -33,3 +33,4 @@ CLAUDE.md
 # macOS font catalogs (downloaded via rake task)
 /spec/fixtures/macos_catalogs/com_apple_MobileAsset_Font*.xml
 
+.lycheecache

data/Gemfile

@@ -5,6 +5,7 @@ gemspec
 
 gem "bundler"
 gem "openssl", "~> 3.0"
+gem "ostruct"
 gem "pry"
 gem "rake"
 gem "rspec"

data/docs/.vitepress/config.ts

@@ -125,6 +125,23 @@ export default defineConfig({
             },
           ],
         },
+        {
+          text: "Platforms",
+          collapsed: true,
+          items: [
+            { text: "Overview", link: "/guide/platforms/" },
+            { text: "macOS", link: "/guide/platforms/macos" },
+            { text: "Windows", link: "/guide/platforms/windows" },
+          ],
+        },
+        {
+          text: "Maintainer Docs",
+          collapsed: true,
+          items: [
+            { text: "Overview", link: "/guide/maintainer/" },
+            { text: "Importing Fonts", link: "/guide/maintainer/import" },
+          ],
+        },
       ],
       "/cli/": [
         {

data/docs/cli/create-formula.md

@@ -41,6 +41,12 @@ fontist create-formula https://example.com/fonts/myfont.zip --file-pattern "*.ot
 
 # Add mirror URLs
 fontist create-formula https://example.com/fonts/myfont.zip --mirror https://mirror.example.com/fonts/myfont.zip
+
+# Create formula with name prefix (for compatibility fonts)
+fontist create-formula https://dl.winehq.org/wine/source/10.x/wine-10.18.tar.xz \
+  --subdir fonts \
+  --file-pattern "*.ttf" \
+  --name-prefix "Wine "
 ```
 
 ## How It Works

data/docs/cli/import.md

@@ -2,6 +2,10 @@
 
 Import fonts from external sources and create Fontist formulas.
 
+::: warning Maintainer Only
+These commands are for Fontist formula maintainers only. End users should use [`fontist install`](/cli/install) to install fonts from the official repository.
+:::
+
 ## Subcommands
 
 | Command | Description |

data/docs/guide/formulas.md

@@ -184,6 +184,79 @@ Private repos are stored alongside the main formulas:
 
 See the [repo command reference](/cli/repo) for complete command documentation.
 
+---
+
+## Advanced Formula Features
+
+### Overriding Font Metadata
+
+Some fonts (especially older ones) contain inconsistent or imperfect metadata. For example, some fonts apply different OTF `Family` values for different font styles, which prevents all styles from being registered under the same family.
+
+The `override:` key allows you to correct metadata without modifying the font files:
+
+```yaml
+fonts:
+- name: Frutiger 45 Light
+  styles:
+  - family_name: Frutiger 45 Light
+    type: Regular
+    full_name: Frutiger-Light
+    post_script_name: Frutiger-Light
+    override:
+      preferred_family_name: Frutiger
+```
+
+This override:
+- Does not modify the actual font file
+- Only affects Fontist's internal indexing
+- Allows all Frutiger fonts to be installed together:
+
+```sh
+fontist install "Frutiger" --preferred-family
+```
+
+### HTTP Authentication
+
+Private formula repositories may require authentication. Configure this when setting up the repository:
+
+```sh
+# GitLab example with private token
+fontist repo setup company-fonts \
+  "https://user:${PRIVATE_TOKEN}@gitlab.com/company/font-formulas.git"
+```
+
+### Authorization Headers
+
+For private archives (e.g., GitHub releases), add authorization headers to the formula:
+
+```yaml
+resources:
+  fonts.zip:
+    urls:
+    - url: https://github.com/company/fonts/releases/assets/12345
+      headers:
+        Accept: application/octet-stream
+        Authorization: token ghp_your_token_here
+```
+
+::: warning Token Scopes
+GitHub tokens need at least the `repo` scope for access to release assets. Generate tokens at [GitHub Settings > Tokens](https://github.com/settings/tokens).
+:::
+
+### Name Prefix Option
+
+When creating formulas for compatibility or replacement fonts, use `--name-prefix` to distinguish them:
+
+```sh
+# Create formula for Wine compatibility fonts
+fontist create-formula https://dl.winehq.org/wine/source/10.x/wine-10.18.tar.xz \
+  --subdir fonts \
+  --file-pattern '*.ttf' \
+  --name-prefix 'Wine '
+```
+
+This generates a formula where all fonts have names prefixed with "Wine ", making it clear these are Wine compatibility fonts rather than the original Microsoft fonts.
+
 ## Related
 
 - [How Fontist Works](/guide/how-it-works) - Internal architecture and indexes

data/docs/guide/installation.md

@@ -43,6 +43,34 @@ macOS comes with Ruby pre-installed. If you encounter permission issues, conside
 
 On Windows, we recommend using [RubyInstaller](https://rubyinstaller.org/) which includes the DevKit needed for native extensions.
 
+#### Windows Installation Steps
+
+1. **Download RubyInstaller** from [rubyinstaller.org](https://rubyinstaller.org/downloads/)
+   - Select the **"Ruby+Devkit"** version (not the plain Ruby version)
+   - Example: `Ruby+Devkit 3.2.X (x64)`
+
+2. **Run the installer**
+   - Check "Add Ruby executables to your PATH"
+   - Check "Associate .rb files with this Ruby installation"
+
+3. **Set up MSYS2** (required for native extensions):
+   ```powershell
+   ridk install
+   ```
+   Select option **3** (MSYS2 and MINGW development toolchain) when prompted.
+
+4. **Install Git for Windows** from [git-scm.com](https://git-scm.com/download/win)
+   - Required for `fontist update` and `fontist repo` commands
+
+5. **Verify installation**:
+   ```powershell
+   ruby --version
+   gem install fontist
+   fontist version
+   ```
+
+See the [Windows Platform Guide](/guide/platforms/windows) for Windows-specific considerations.
+
 ### Linux
 
 Most Linux distributions have Ruby available through their package managers:
@@ -94,6 +122,40 @@ sudo dnf install gcc ruby-devel
 xcode-select --install
 ```
 
+## Native Dependencies
+
+Fontist depends on several gems with native C/C++ extensions. The following table shows what's required:
+
+| Gem | Compiler | Purpose |
+|-----|----------|---------|
+| `json` | gcc | JSON parsing |
+| `brotli` (via fontisan) | gcc | WOFF2 font decompression |
+| `seven-zip` (via excavate) | g++ | 7z archive extraction |
+| `libmspack` (via excavate) | gcc | CAB/CHM archive extraction |
+| `ffi-libarchive-binary` (via excavate) | gcc | Archive extraction (zip, tar, etc.) |
+
+::: note Prebuilt Binaries
+Some gems like `nokogiri` and `ffi` provide prebuilt binaries for common platforms, so they typically don't require compilation.
+:::
+
+### Windows DevKit Setup
+
+On Windows, native extensions require the RubyInstaller DevKit:
+
+1. Download [RubyInstaller](https://rubyinstaller.org/downloads/) with DevKit (select "Ruby+Devkit" version)
+
+2. Run the installer, checking "Add Ruby executables to your PATH"
+
+3. After installation, run the following in a command prompt:
+
+   ```cmd
+   ridk install
+   ```
+
+4. Select option **3** (MSYS2 and MINGW development toolchain) when prompted
+
+5. Install [Git for Windows](https://git-scm.com/download/win) for `fontist update` and `fontist repo` commands
+
 ### Proxy Configuration
 
 If you're behind a proxy, configure Git to use it:

data/docs/guide/maintainer/import.md

@@ -0,0 +1,372 @@
+---
+title: Importing Fonts from External Sources
+---
+
+# Importing Fonts from External Sources
+
+::: warning Maintainer Only
+The documentation is for Fontist formula maintainers only. End users should use `fontist install` to install fonts from the official repository.
+:::
+
+Fontist can automatically generate formulas from external font sources including Google Fonts, macOS supplementary fonts, and SIL International fonts.
+
+---
+
+## Google Fonts Import
+
+### Overview
+
+[Google Fonts](https://fonts.google.com) provides the largest collection of freely licensed fonts. Fontist maintains formulas for all Google Fonts and supports importing them.
+
+### Data Sources
+
+The Google Fonts importer uses multiple data sources:
+
+#### Four Equal Data Sources
+
+| Source | Provides |
+|--------|----------|
+| **Ttf** (API) | TTF download URLs |
+| **Vf** (API) | Variable font URLs + axes information |
+| **Woff2** (API) | WOFF2 web font URLs |
+| **Github** (Repo) | Font metadata (designer, license, category) |
+
+### Architecture
+
+The importer uses a layered architecture.
+
+```
+        ┌──────────────────────────┐
+        │   FontDatabase           │
+        │   (Single Entry Point)   │
+        └───────────┬──────────────┘
+                    │
+      ┌─────────────┼─────────────┬─────────────┐
+      │             │             │             │
+      ▼             ▼             ▼             ▼
+┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
+│   Ttf    │  │    Vf    │  │  Woff2   │  │  Github  │
+│  (API)   │  │  (API)   │  │  (API)   │  │  (Repo)  │
+└──────────┘  └──────────┘  └──────────┘  └──────────┘
+
+All 4 Data Sources Are Equal
+```
+
+### Prerequisites
+
+1. **Local checkout** of the [google/fonts](https://github.com/google/fonts) repository
+
+2. **Google Fonts API key** (get one from [Google Cloud Console](https://console.cloud.google.com/))
+
+   ```sh
+   export GOOGLE_FONTS_API_KEY="your_api_key_here"
+   ```
+
+### Import Command
+
+Import all Google Fonts.
+
+```sh
+fontist import google \
+  --source-path /path/to/google/fonts \
+  --output-path Formulas/google \
+  --verbose \
+  --import-cache /tmp/fontist-google-cache
+```
+
+Import a single font family.
+
+```sh
+fontist import google \
+  --font-family "Roboto" \
+  --source-path /path/to/google/fonts \
+  --verbose
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--source-path` | Path to checked-out google/fonts repository |
+| `--output-path` | Output directory for generated formulas (default: `./Formulas/google`) |
+| `--font-family` | Import specific font family by name |
+| `--force` | Overwrite existing formulas |
+| `--verbose` | Enable detailed progress output |
+| `--import-cache` | Directory for caching downloaded archives |
+
+### Ruby API
+
+```ruby
+require 'fontist/import/google/font_database'
+
+# Build database from all 4 sources
+db = Fontist::Import::Google::FontDatabase.build(
+  api_key: ENV['GOOGLE_FONTS_API_KEY'],
+  source_path: '/path/to/google/fonts'
+)
+
+# Query merged data
+roboto = db.font_by_name('Roboto')
+puts roboto.designer      # From Github repository
+puts roboto.axes.count    # From API (VF endpoint)
+
+# Generate formulas
+db.save_formulas('./formulas')              # All fonts
+db.save_formulas('./formulas', family_name: 'Roboto')  # Single font
+```
+
+### Automated Updates
+
+Fontist uses a [GitHub Actions workflow](https://github.com/fontist/formulas/blob/v4/.github/workflows/google.yml) to check for updated fonts on Google Fonts daily.
+
+New, updated, or removed fonts are automatically committed to the [Fontist formula repository](https://github.com/fontist/formulas).
+
+---
+
+## SIL Fonts Import
+
+### Overview
+
+[SIL International](https://www.sil.org) is an organization that serves language communities worldwide. SIL provides unique fonts supporting smaller language communities with Unicode support often not available in mainstream fonts.
+
+### Import Command
+
+Import all SIL fonts.
+
+```sh
+fontist import sil \
+  --output-path Formulas/sil \
+  --verbose \
+  --import-cache /tmp/sil-import-cache
+```
+
+Import a single SIL font.
+
+```sh
+fontist import sil \
+  --font-name "Andika" \
+  --output-path Formulas/sil \
+  --verbose \
+  --import-cache /tmp/sil-import-cache
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--output-path` | Output directory for generated formulas |
+| `--font-name` | Import specific font by name |
+| `--force` | Overwrite existing formulas |
+| `--verbose` | Enable detailed progress output |
+| `--import-cache` | Directory for caching downloaded archives |
+
+---
+
+## macOS Supplementary Fonts Import
+
+### Overview
+
+macOS supplementary fonts use multi-dimensional versioning with framework versions, catalog posted dates, and asset build IDs.
+
+### Import Command
+
+Import from macOS font catalogs.
+
+```sh
+fontist import macos \
+  --plist com_apple_MobileAsset_Font7.xml \
+  --output-path Formulas/macos/font7 \
+  --verbose \
+  --import-cache /tmp/fontist-macos-cache \
+  --force
+```
+
+Import a single macOS font.
+
+```sh
+fontist import macos \
+  --plist com_apple_MobileAsset_Font7.xml \
+  --font-name "Hiragino" \
+  --output-path Formulas/macos/font7 \
+  --verbose
+```
+
+### Finding Catalog Files
+
+Run `fontist macos-catalogs` to list available font catalogs on your system.
+
+### Catalog URLs
+
+Catalogs are also available from Apple's Mobile Asset Server.
+
+| Version | URL |
+|---------|-----|
+| Font 3 | `https://mesu.apple.com/assets/macos/com_apple_MobileAsset_Font3/com_apple_MobileAsset_Font3.xml` |
+| Font 4 | `https://mesu.apple.com/assets/macos/com_apple_MobileAsset_Font4/com_apple_MobileAsset_Font4.xml` |
+| Font 5 | `https://mesu.apple.com/assets/macos/com_apple_MobileAsset_Font5/com_apple_MobileAsset_Font5.xml` |
+| Font 6 | `https://mesu.apple.com/assets/macos/com_apple_MobileAsset_Font6/com_apple_MobileAsset_Font6.xml` |
+| Font 7 | `https://mesu.apple.com/assets/macos/com_apple_MobileAsset_Font7/com_apple_MobileAsset_Font7.xml` |
+| Font 8 | `https://mesu.apple.com/assets/macos/com_apple_MobileAsset_Font8/com_apple_MobileAsset_Font8.xml` |
+
+---
+
+## Import Source Architecture
+
+### Import Source Attribute
+
+Formulas with import sources track metadata about their origin.
+
+#### macOS Import Source
+
+```yaml
+import_source:
+  type: macos
+  framework_version: 7
+  posted_date: "2024-08-13T18:11:00Z"
+  asset_id: "10m1360"
+```
+
+#### Google Fonts Import Source
+
+```yaml
+import_source:
+  type: google
+  commit_id: "abc123def456"
+  api_version: "v1"
+  last_modified: "2024-01-01T12:00:00Z"
+  family_id: "roboto"
+```
+
+#### SIL Import Source
+
+```yaml
+import_source:
+  type: sil
+  version: "1.0.0"
+  release_date: "2024-01-01"
+```
+
+### Versioned Filenames
+
+Import source type determines filename format.
+
+| Source | Format | Example |
+|--------|--------|---------|
+| macOS | `{name}_{asset_id}.yml` | `al_bayan_10m1360.yml` |
+| Google | `{name}.yml` | `roboto.yml` (no versioning) |
+| SIL | `{name}_{version}.yml` | `charis_sil_6.200.yml` |
+
+### Why Different Strategies?
+
+- **macOS**: Multiple versions coexist for different macOS versions
+- **Google**: Live service always points to latest; commit tracked for metadata only
+- **SIL**: Versioned releases need coexistence
+
+---
+
+## Import Cache Management
+
+### Overview
+
+During formula imports, Fontist downloads font archives for analysis. The import cache optimizes performance and avoids redundant downloads.
+
+Default location: `~/.fontist/import_cache`
+
+### Configuration Methods
+
+#### CLI Option
+
+```sh
+fontist import google --import-cache /custom/path ...
+fontist import macos --import-cache /custom/path ...
+fontist import sil --import-cache /custom/path ...
+```
+
+#### Ruby API
+
+```ruby
+# Global setting
+Fontist.import_cache_path = "/custom/import/cache"
+
+# Per-import setting
+Fontist::Import::Macos.new(
+  plist_path,
+  import_cache: "/custom/cache"
+).call
+```
+
+#### Environment Variable
+
+```sh
+export FONTIST_IMPORT_CACHE=/custom/import/cache
+fontist import macos ...
+```
+
+### Cache Management
+
+Clear the import cache.
+
+```sh
+fontist cache clear-import
+```
+
+View cache information.
+
+```sh
+fontist cache info
+```
+
+---
+
+## Verbose Output
+
+Enable `--verbose` for detailed progress tracking.
+
+```sh
+fontist import macos --plist catalog.xml --verbose
+```
+
+Output includes.
+
+- Paint-colored headers with Unicode box characters
+- Import cache location
+- Download URLs and cache status
+- Extraction directory paths
+- Real-time progress with percentages
+- Per-font status indicators
+- Detailed summary statistics
+
+### Example Output
+
+```
+════════════════════════════════════════════════════════════════════
+  📦 macOS Supplementary Fonts Import
+════════════════════════════════════════════════════════════════════
+
+📦 Import cache: /Users/user/.fontist/import_cache
+📁 Output path: /Users/user/.fontist/versions/v4/formulas/Formulas/macos/font7
+
+(1/3) 33.3% | Hiragino Sans (2 fonts)
+Downloading from: https://updates.cdn-apple.com/.../font.zip
+  Cache location: /Users/user/.fontist/import_cache
+  Extracting to: /var/folders/.../temp
+  Extraction cache cleared
+  ✓ Formula created: hiragino_sans_10m1044.yml (3.98s)
+
+════════════════════════════════════════════════════════════════════
+  📊 Import Summary
+════════════════════════════════════════════════════════════════════
+
+  Total packages:     3
+  ✓ Successful:     3 (100.0%)
+
+  🎉 Great success! 3 formulas created!
+```
+
+---
+
+## See Also
+
+- [Formulas Guide](/guide/formulas) - How formulas work
+- [repo Command](/cli/repo) - Managing formula repositories
+- [cache Command](/cli/cache) - Cache management

data/docs/guide/maintainer/index.md

@@ -0,0 +1,37 @@
+---
+title: Maintainer Documentation
+---
+
+# Maintainer Documentation
+
+::: warning For Fontist Maintainers Only
+This section contains documentation for Fontist formula maintainers. End users typically do not need these commands.
+:::
+
+## Topics
+
+### [Import Commands](/guide/maintainer/import)
+
+Import fonts from external sources to create Fontist formulas:
+- Google Fonts
+- macOS supplementary fonts
+- SIL International fonts
+
+---
+
+## Who Should Use These Commands?
+
+You should use these commands if you are:
+
+- A **Fontist formula maintainer** updating the official formula repository
+- Creating formulas from **large font collections** (Google Fonts, macOS, SIL)
+- Contributing new formulas to the **fontist/formulas** repository
+
+## Regular Users
+
+If you just want to install fonts, you don't need these commands. Instead:
+
+- Use `fontist install "Font Name"` to install fonts
+- Use `fontist create-formula <url>` to create a single formula from a font archive
+
+See the [Getting Started Guide](/guide/) for regular usage.