fontist 2.1.4 → 2.1.6

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.

data/docs/guide/platforms/index.md

@@ -0,0 +1,72 @@
+---
+title: Platform Guides
+---
+
+# Platform Guides
+
+Fontist works consistently across macOS, Windows, and Linux, but each platform has unique characteristics and features.
+
+## Available Platform Guides
+
+### [macOS](/guide/platforms/macos)
+
+Learn about:
+- macOS supplementary fonts framework
+- Framework versioning (Font3-Font8)
+- Platform-specific font installation
+- Version compatibility
+
+### [Windows](/guide/platforms/windows)
+
+Learn about:
+- Windows font locations
+- Administrator privileges
+- File locking considerations
+- Troubleshooting Windows-specific issues
+
+---
+
+## Quick Comparison
+
+| Feature | macOS | Windows | Linux |
+|---------|-------|---------|-------|
+| System fonts | `/Library/Fonts` | `C:\Windows\Fonts` | `/usr/share/fonts` |
+| User fonts | `~/Library/Fonts` | `%LOCALAPPDATA%\...\Fonts` | `~/.local/share/fonts` |
+| Supplementary fonts | ✅ Framework | ❌ | ❌ |
+| Fontconfig | ✅ Optional | ✅ Optional | ✅ Recommended |
+| Admin for system | Yes | Yes | Yes |
+
+---
+
+## Platform-Specific Features
+
+### macOS Supplementary Fonts
+
+macOS includes a supplementary fonts framework for licensed fonts. Fontist can install these fonts automatically:
+
+```sh
+fontist install "Canela"
+```
+
+See the [macOS guide](/guide/platforms/macos) for details.
+
+### Windows Font Management
+
+Windows uses different font locations and has stricter file locking:
+
+```powershell
+# Install to user fonts (no admin needed)
+fontist install "Roboto" --location user
+```
+
+See the [Windows guide](/guide/platforms/windows) for details.
+
+### Linux Fontconfig
+
+On Linux, Fontist integrates with fontconfig to make fonts available system-wide:
+
+```sh
+fontist fontconfig update
+```
+
+See the [Fontconfig guide](/guide/fontconfig) for details.

data/docs/guide/platforms/macos.md

@@ -0,0 +1,151 @@
+---
+title: macOS Platform Guide
+---
+
+# macOS Platform Guide
+
+Fontist provides special support for macOS supplementary fonts, a framework introduced in macOS 10.12 (Sierra) for dynamically downloading licensed fonts on demand.
+
+## Supplementary Fonts Overview
+
+macOS provides a "supplementary fonts" framework (shared with iOS) for dynamically downloading and installing a wide range of licensed fonts. These fonts are typically commercial fonts that come free with macOS.
+
+### Typical Use Cases
+
+- CI jobs on macOS environments using specially-licensed fonts
+- Automating installation of macOS add-on fonts
+- Accessing platform-specific fonts not available elsewhere
+
+::: warning Non-macOS Installation
+Fontist does not allow installing macOS-specific fonts on non-macOS platforms due to font license restrictions.
+:::
+
+---
+
+## Framework Versioning
+
+The macOS supplementary font catalog is bound to specific framework versions. Different versions contain different sets of fonts, and often different versions of the same fonts.
+
+### Version Compatibility
+
+| macOS Version | Framework Version | Platform Tag |
+|---------------|-------------------|--------------|
+| macOS 10.12 (Sierra) | Font 3 | `macos-font3` |
+| macOS 10.13 (High Sierra) | Font 4 | `macos-font4` |
+| macOS 10.14 (Mojave) | Font 5 | `macos-font5` |
+| macOS 10.15 (Catalina) | Font 6 | `macos-font6` |
+| macOS 11 (Big Sur) | Font 6 | `macos-font6` |
+| macOS 12 (Monterey) | Font 7 | `macos-font7` |
+| macOS 13 (Ventura) | Font 7 | `macos-font7` |
+| macOS 14 (Sonoma) | Font 7 | `macos-font7` |
+| macOS 15 (Sequoia) | Font 7 | `macos-font7` |
+| macOS 26+ (Tahoe) | Font 8 | `macos-font8` |
+
+### How Versioning Works
+
+A macOS system can only download fonts from the catalog version corresponding to its framework version. Fontist respects this limitation when installing these fonts.
+
+When you install a macOS add-on font, Fontist automatically detects your macOS version and installs the appropriate font version:
+
+```sh
+fontist install "Al Bayan"
+# On macOS 15: installs Font7 version formula
+# On macOS 26: installs Font8 version formula
+```
+
+This ensures you always get the font version compatible with your system.
+
+---
+
+## Platform Tags
+
+In Fontist Formulas, each supplementary font is backed by a formula specifying the font framework version using platform tags.
+
+### Tag Format
+
+Platform tags follow the pattern: `macos-fontX` where `X` is the catalog version number.
+
+### Version Compatibility Checking
+
+Fontist controls version compatibility through platform tags:
+
+```sh
+# On macOS 14.2 (Sonoma), trying to install a Font8-only formula:
+fontist install "Font8OnlyFont"
+
+# Error output:
+# Font 'Font8OnlyFont' is only available for: macos-font8.
+# Your current platform is: macos. Your macOS version is: 14.2.1.
+# This font requires macOS 26.0 or later.
+# This font cannot be installed on your system.
+```
+
+---
+
+## Manual Installation Methods
+
+On macOS, supplementary fonts can also be installed manually:
+
+### Method 1: Application Trigger
+
+User applications can trigger installation when needed, as described in Apple's ["DownloadFont" sample code](https://developer.apple.com/library/archive/samplecode/DownloadFont/Introduction/Intro.html).
+
+### Method 2: Font Book
+
+1. Open **Font Book.app**
+2. Search for the desired font
+3. Click "Download"
+
+Both methods trigger a download from Apple's Mobile Asset Server.
+
+---
+
+## Asset Catalog Locations
+
+The asset catalog XML files are located at:
+
+| Version | System Path |
+|---------|-------------|
+| Font 3 | `/System/Library/Assets/com_apple_MobileAsset_Font3/com_apple_MobileAsset_Font3.xml` |
+| Font 4 | `/System/Library/Assets/com_apple_MobileAsset_Font4/com_apple_MobileAsset_Font4.xml` |
+| Font 5 | `/System/Library/AssetsV2/com_apple_MobileAsset_Font5/com_apple_MobileAsset_Font5.xml` |
+| Font 6 | `/System/Library/AssetsV2/com_apple_MobileAsset_Font6/com_apple_MobileAsset_Font6.xml` |
+| Font 7 | `/System/Library/AssetsV2/com_apple_MobileAsset_Font7/com_apple_MobileAsset_Font7.xml` |
+| Font 8 | `/System/Library/AssetsV2/com_apple_MobileAsset_Font8/com_apple_MobileAsset_Font8.xml` |
+
+::: note Schema Differences
+The Assets and AssetsV2 frameworks use slightly different Plist schemas.
+:::
+
+---
+
+## Font Sources by macOS Version
+
+For the complete list of available fonts on each macOS version, see Apple's support pages:
+
+| macOS Version | Apple Support Link |
+|---------------|-------------------|
+| macOS 15 (Sequoia) | [Fonts included with macOS Sequoia](https://support.apple.com/en-us/120414) |
+| macOS 14 (Sonoma) | [Fonts included with macOS Sonoma](https://support.apple.com/en-us/108939) |
+
+::: note Older macOS Versions
+Apple may remove or relocate support articles for older macOS versions. For Ventura, Monterey, Big Sur, and earlier versions, use Font Book on your Mac to view available fonts, or search Apple Support for the specific version.
+:::
+
+---
+
+## Example: Installing Canela
+
+Canela is a commercial font that comes free with macOS:
+
+```sh
+fontist install Canela
+```
+
+---
+
+## See Also
+
+- [How Fontist Works](/guide/how-it-works) - Architecture and indexes
+- [Formulas Guide](/guide/formulas) - How formulas work
+- [Fontist Blog: Installing macOS-specific add-on fonts](https://www.fontist.org/blog/2022-02-11-macos-fonts)