fontist 2.1.4 → 2.1.5

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)

data/docs/guide/platforms/windows.md

@@ -0,0 +1,220 @@
+---
+title: Windows Platform Guide
+---
+
+# Windows Platform Guide
+
+Fontist provides comprehensive Windows platform support, allowing installation and management of fonts on Windows 7 and later.
+
+## Windows Font Management
+
+Windows font management differs from Unix systems in several key ways:
+
+| Difference | Description |
+|------------|-------------|
+| Path separator | Uses backslash (`\`) instead of forward slash (`/`) |
+| Font locations | Registry-based and directory-based locations |
+| File locking | Stricter file locking during operations |
+| Permissions | Case-insensitive but case-preserving filesystem |
+
+---
+
+## Windows Font Locations
+
+Fontist supports three installation locations on Windows:
+
+### System Fonts
+
+| Property | Value |
+|----------|-------|
+| Location | `C:\Windows\Fonts` |
+| Requires Admin | Yes |
+| Available To | All users |
+
+### User Fonts
+
+| Property | Value |
+|----------|-------|
+| Location | `%LOCALAPPDATA%\Microsoft\Windows\Fonts` |
+| Requires Admin | No |
+| Available To | Current user only |
+| Windows Version | Windows 10+ |
+
+### Fontist Library
+
+| Property | Value |
+|----------|-------|
+| Location | `%USERPROFILE%\.fontist\fonts` |
+| Requires Admin | No |
+| Available To | Current user only |
+| Default | Yes |
+
+Fontist creates a `fontist` subdirectory within user and system font directories to avoid cluttering the main font directory.
+
+---
+
+## Installation Examples
+
+### Install to Fontist Library (Default)
+
+```powershell
+# No administrator privileges required
+fontist install "Roboto"
+```
+
+### Install to User Fonts Directory
+
+```powershell
+# No administrator privileges required (Windows 10+)
+fontist install "Roboto" --location=user
+```
+
+### Install to System Fonts Directory
+
+```powershell
+# Run as Administrator
+fontist install "Roboto" --location=system
+```
+
+---
+
+## Windows-Specific Considerations
+
+### File Locking
+
+Windows uses stricter file locking than Unix systems. Fontist handles this with automatic retry logic when encountering locked files during cleanup operations.
+
+If you encounter file locking issues:
+1. Close applications that might be using the font
+2. Retry the operation
+3. Use Task Manager to identify processes locking the file
+
+### Path Handling
+
+Fontist automatically handles Windows path separators and drive letters. Font paths are returned in Windows-native format:
+
+```
+C:\Users\user\.fontist\fonts\font.ttf
+```
+
+### Registry Integration
+
+While Windows historically used registry-based font registration, modern Windows (10+) supports directory-based fonts. Fontist uses directory-based installation for maximum compatibility and ease of management.
+
+### Administrator Privileges
+
+| Operation | Admin Required |
+|-----------|----------------|
+| Install to `fontist` location | No |
+| Install to `user` location | No |
+| Install to `system` location | Yes |
+| Uninstall from system fonts | Yes |
+
+---
+
+## Platform Compatibility
+
+| Windows Version | Support Status | Notes |
+|-----------------|----------------|-------|
+| Windows 11 | ✅ Fully Supported | All features available |
+| Windows 10 | ✅ Fully Supported | User font directory available |
+| Windows 8/8.1 | ✅ Supported | System and fontist locations only |
+| Windows 7 | ⚠️ Limited Support | System and fontist locations only |
+
+::: warning Windows 7 Support
+Extended support for Windows 7 ended January 14, 2020. Fontist is tested on Windows 10 and later. Earlier versions may work but are not actively tested.
+:::
+
+---
+
+## Ruby Installation on Windows
+
+### Prerequisites
+
+1. **RubyInstaller with DevKit** - Required for native gem extensions
+2. **MSYS2** - Required for building native extensions
+3. **Git for Windows** - Required for `fontist update` and `fontist repo` commands
+
+### Installation Steps
+
+1. Download [RubyInstaller](https://rubyinstaller.org/downloads/) (select "Ruby+Devkit" version)
+
+2. Run the installer and check "Add Ruby executables to your PATH"
+
+3. After installation, run MSYS2 setup:
+   ```powershell
+   ridk install
+   ```
+   Select option 3 (MSYS2 and MINGW development toolchain) when prompted.
+
+4. Install [Git for Windows](https://git-scm.com/download/win)
+
+5. Install Fontist:
+   ```powershell
+   gem install fontist
+   ```
+
+---
+
+## Troubleshooting
+
+### Native Extension Errors
+
+If you see errors about failed compilations:
+
+```powershell
+# Ensure MSYS2 is properly installed
+ridk install
+
+# Reinstall the gem with verbose output
+gem install fontist --verbose
+```
+
+### Permission Errors
+
+If you get permission errors:
+
+```powershell
+# Option 1: Install to user directory
+fontist install "Roboto" --location=user
+
+# Option 2: Run as Administrator for system fonts
+# Right-click PowerShell → "Run as administrator"
+fontist install "Roboto" --location=system
+```
+
+### Path Too Long Errors
+
+Windows has a 260 character path limit by default. If you encounter path issues:
+
+1. Enable long paths in Windows (requires admin):
+   ```powershell
+   # Run as Administrator
+   New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
+     -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
+   ```
+
+2. Or use a shorter installation path via environment variable:
+   ```powershell
+   $env:FONTIST_PATH = "C:\f"
+   fontist install "Roboto"
+   ```
+
+---
+
+## Environment Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `FONTIST_PATH` | Base directory for Fontist data | `C:\fontist` |
+| `FONTIST_INSTALL_LOCATION` | Default install location | `user` |
+| `FONTIST_USER_FONTS_PATH` | Custom user fonts path | `C:\Users\me\Fonts` |
+| `FONTIST_SYSTEM_FONTS_PATH` | Custom system fonts path | `C:\Windows\Fonts` |
+
+---
+
+## See Also
+
+- [Installation Guide](/guide/installation) - General installation instructions
+- [Install Command](/cli/install) - CLI reference for install
+- [How Fontist Works](/guide/how-it-works) - Architecture overview

data/fontist.gemspec

@@ -36,7 +36,6 @@ Gem::Specification.new do |spec|
   spec.add_dependency "git", "> 1.0"
   spec.add_dependency "json", "~> 2.0"
   spec.add_dependency "lutaml-model", "~> 0.7"
-  spec.add_dependency "lutaml-xsd", "~> 1.0"
   spec.add_dependency "marcel", "~> 1.0"
   spec.add_dependency "nokogiri", "~> 1.0"
   spec.add_dependency "octokit", "~> 4.0"

data/lib/fontist/cache/manager.rb

@@ -1,5 +1,3 @@
-require_relative "store"
-
 module Fontist
   module Cache
     # Central cache manager for font index caching operations

data/lib/fontist/cache.rb

@@ -0,0 +1,6 @@
+module Fontist
+  module Cache
+    autoload :Store, "#{__dir__}/cache/store"
+    autoload :Manager, "#{__dir__}/cache/manager"
+  end
+end

data/lib/fontist/cli/thor_ext.rb

@@ -1,5 +1,3 @@
-require "fontist/utils/ui"
-
 module Fontist
   module ThorExt
     # Sources:

data/lib/fontist/cli.rb

@@ -1,13 +1,6 @@
 require "thor"
 require_relative "cli/class_options"
 require_relative "cli/thor_ext"
-require_relative "repo_cli"
-require_relative "cache_cli"
-require_relative "import_cli"
-require_relative "fontconfig_cli"
-require_relative "config_cli"
-require_relative "index_cli"
-require_relative "manifest_cli"
 
 module Fontist
   class CLI < Thor
@@ -248,7 +241,6 @@ module Fontist
                                "e.g. 'Wine ' for compatibility fonts"
     def create_formula(url)
       handle_class_options(options)
-      require "fontist/import/create_formula"
       name = Fontist::Import::CreateFormula.new(url, options).call
       Fontist.ui.say("#{name} formula has been successfully created")
       success
@@ -271,7 +263,6 @@ module Fontist
     desc "macos-catalogs", "List available macOS font catalogs"
     def macos_catalogs
       handle_class_options(options)
-      require_relative "macos/catalog/catalog_manager"
 
       catalogs = Fontist::Macos::Catalog::CatalogManager.available_catalogs
 

data/lib/fontist/collection_file.rb

@@ -1,5 +1,4 @@
 require "fontisan"
-require_relative "errors"
 
 module Fontist
   class CollectionFile
@@ -18,8 +17,6 @@ module Fontist
       def build_collection(path)
         # Validate collection by checking it can be loaded
         # This uses fontisan's collection validation infrastructure
-        require "fontisan"
-
         # First check if it's a valid collection file
         unless Fontisan::FontLoader.collection?(path)
           raise Errors::FontFileError,

data/lib/fontist/font.rb

@@ -1,9 +1,3 @@
-require "fontist/font_installer"
-require "fontist/font_path"
-require "fontist/formula_picker"
-require "fontist/fontconfig"
-require "fontist/formula_suggestion"
-
 module Fontist
   class Font
     def initialize(options = {})

data/lib/fontist/font_collection.rb

@@ -1,5 +1,4 @@
 require "lutaml/model"
-require_relative "font_model"
 
 module Fontist
   class FontCollection < Lutaml::Model::Serializable

data/lib/fontist/font_file.rb

@@ -1,6 +1,5 @@
 require "fontisan"
 require "tempfile"
-require_relative "errors"
 
 module Fontist
   class FontFile

data/lib/fontist/font_installer.rb

@@ -1,9 +1,4 @@
-require "fontist/utils"
 require "excavate"
-require_relative "resources/archive_resource"
-require_relative "resources/google_resource"
-require_relative "resources/apple_cdn_resource"
-require_relative "install_location"
 
 module Fontist
   class FontInstaller

data/lib/fontist/font_model.rb

@@ -1,5 +1,4 @@
 require "lutaml/model"
-require_relative "font_style"
 
 module Fontist
   class FontModel < Lutaml::Model::Serializable

data/lib/fontist/font_path.rb

@@ -1,5 +1,3 @@
-require "fontist/indexes/filename_index"
-
 module Fontist
   class FontPath
     def initialize(path)

data/lib/fontist/formula.rb

@@ -1,19 +1,7 @@
 require "lutaml/model"
-require_relative "font_model"
-require_relative "font_collection"
-require_relative "extract"
-require_relative "index"
-require_relative "helpers"
-require_relative "update"
-require_relative "import_source"
-require_relative "macos_import_source"
-require_relative "google_import_source"
-require_relative "sil_import_source"
 require "git"
 
 module Fontist
-  require "lutaml/model"
-
   class Resource < Lutaml::Model::Serializable
     attribute :name, :string
     attribute :source, :string
@@ -280,7 +268,6 @@ module Fontist
         # Check if framework exists for this macOS version
         framework = Utils::System.catalog_version_for_macos
         if framework.nil?
-          require_relative "macos_framework_metadata"
           raise Errors::UnsupportedMacOSVersionError.new(
             current_macos,
             MacosFrameworkMetadata.metadata,

data/lib/fontist/formula_picker.rb

@@ -1,5 +1,3 @@
-require "fontist/style_version"
-
 module Fontist
   class FormulaPicker
     def initialize(font_name, size_limit:, version:, smallest:, newest:)

data/lib/fontist/google_import_source.rb

@@ -1,5 +1,3 @@
-require_relative "import_source"
-
 module Fontist
   # Import source for Google Fonts
   #

data/lib/fontist/import/convert_formulas.rb

@@ -1,5 +1,3 @@
-require_relative "formula_serializer"
-
 module Fontist
   module Import
     class ConvertFormulas

data/lib/fontist/import/create_formula.rb

@@ -1,7 +1,3 @@
-require "fontist/import"
-require_relative "recursive_extraction"
-require_relative "formula_builder"
-
 module Fontist
   module Import
     class CreateFormula

data/lib/fontist/import/files/collection_file.rb

@@ -1,5 +1,4 @@
 require "fontisan"
-require_relative "../otf/font_file"
 
 module Fontist
   module Import

data/lib/fontist/import/files.rb

@@ -0,0 +1,8 @@
+module Fontist
+  module Import
+    module Files
+      autoload :CollectionFile, "#{__dir__}/files/collection_file"
+      autoload :FontDetector, "#{__dir__}/files/font_detector"
+    end
+  end
+end

data/lib/fontist/import/font_metadata_extractor.rb

@@ -1,5 +1,4 @@
 require "fontisan"
-require_relative "models/font_metadata"
 
 module Fontist
   module Import

data/lib/fontist/import/formula_builder.rb

@@ -1,10 +1,4 @@
 require "shellwords"
-require_relative "text_helper"
-require_relative "helpers/hash_helper"
-require_relative "recursive_extraction"
-require_relative "../macos_import_source"
-require_relative "../google_import_source"
-require_relative "../sil_import_source"
 
 module Fontist
   module Import

data/lib/fontist/import/google/api.rb

@@ -1,12 +1,3 @@
-require_relative "models/axis"
-require_relative "models/font_variant"
-require_relative "models/font_family"
-require_relative "data_sources/base"
-require_relative "data_sources/ttf"
-require_relative "data_sources/vf"
-require_relative "data_sources/woff2"
-require_relative "font_database"
-
 module Fontist
   module Import
     module Google

data/lib/fontist/import/google/data_sources/base.rb

@@ -1,7 +1,6 @@
 require "net/http"
 require "json"
 require "uri"
-require_relative "../models/font_family"
 
 module Fontist
   module Import