fontist 2.1.3 → 2.1.4

data/docs/guide/concepts/licenses.md

@@ -0,0 +1,236 @@
+---
+title: Font Licenses
+---
+
+# Font Licenses
+
+**Font Licenses** define how fonts can be used, modified, and distributed. Fontist tracks license requirements and prompts for acceptance when needed.
+
+## License Types
+
+### Open Source Licenses
+
+| License | Install | Embed | Modify | Commercial | Notes |
+|---------|---------|-------|--------|------------|-------|
+| SIL OFL 1.1 | ✅ | ✅ | ✅ | ✅ | Most common for fonts |
+| Apache 2.0 | ✅ | ✅ | ✅ | ✅ | Google Fonts default |
+| MIT | ✅ | ✅ | ✅ | ✅ | Permissive |
+| GPLv2 | ✅ | ⚠️ | ✅ | ❌ | Copyleft |
+| LGPL | ✅ | ✅ | ⚠️ | ✅ | Linking exception |
+
+### Proprietary Licenses
+
+| License Type | Install | Embed | Modify | Commercial |
+|--------------|---------|-------|--------|------------|
+| Freeware | ✅ | Varies | ❌ | Varies |
+| Shareware | ⚠️ | ❌ | ❌ | ❌ |
+| Commercial | ⚠️ | ⚠️ | ❌ | ⚠️ |
+| Bundle-only | ✅ | ✅ | ❌ | ✅ |
+
+---
+
+## SIL Open Font License (OFL)
+
+The most common open-source font license, created specifically for fonts.
+
+### Key Points
+
+- **Free to use** - No cost for any use
+- **Free to share** - Redistribute freely
+- **Free to modify** - Create derivative works
+- **Reserved Font Name** - Some fonts restrict use of original name
+- **Bundle allowed** - Include in software packages
+
+### OFL in Practice
+
+```yaml
+# Example OFL font in formula
+name: open-sans
+license:
+  type: OFL-1.1
+  url: https://scripts.sil.org/OFL
+  requires_confirmation: false
+```
+
+---
+
+## Proprietary Fonts
+
+Some fonts require license acceptance before installation.
+
+### Fontist License Handling
+
+```bash
+# Fontist shows license requirements
+fontist install "Calibri"
+
+# Output:
+# This font requires license acceptance.
+# License: Microsoft Software License
+# View license? [y/N]
+```
+
+### Accepting Licenses
+
+```bash
+# For CI/CD, accept all licenses
+fontist install --accept-all-licenses "Calibri"
+```
+
+### In Manifests
+
+```yaml
+# Manifest with license handling
+Calibri:
+  - Regular
+  - Bold
+
+# Install with license acceptance
+# fontist manifest-install --accept-all-licenses manifest.yml
+```
+
+---
+
+## License Metadata in Formulas
+
+Formulas include license information:
+
+```yaml
+name: example-font
+description: Example font with license info
+homepage: https://example.com/font
+
+copyright:
+  - Copyright (c) 2026 Example Foundry
+
+license:
+  type: OFL-1.1
+  url: https://scripts.sil.org/OFL
+  requires_confirmation: false
+
+# OR for proprietary:
+license:
+  type: Proprietary
+  url: https://example.com/license
+  requires_confirmation: true
+  text: |
+    END USER LICENSE AGREEMENT
+    ...
+```
+
+---
+
+## Fontist License Error Handling
+
+### Exit Code 4: Licensing Error
+
+When a font requires license acceptance but it wasn't provided:
+
+```bash
+fontist install "Some Commercial Font"
+# Exit code: 4
+# Error: License confirmation required
+```
+
+### Handling in Scripts
+
+```bash
+#!/bin/bash
+fontist install "Font Name"
+case $? in
+  0) echo "Success" ;;
+  4) echo "License required, accepting..."
+      fontist install --accept-all-licenses "Font Name"
+      ;;
+  *) echo "Error: $?" ;;
+esac
+```
+
+### In Ruby
+
+```ruby
+begin
+  Fontist::Font.install("Font Name")
+rescue Fontist::Errors::LicensingError
+  # Handle license requirement
+  Fontist::Font.install("Font Name", confirmation: "yes")
+end
+```
+
+---
+
+## Embedding Rights
+
+### What is Font Embedding?
+
+Embedding includes the font inside a document (PDF, EPUB, etc.) rather than requiring the recipient to have it installed.
+
+### Embedding Types
+
+| Type | Description |
+|------|-------------|
+| Installable | Font can be installed and used |
+| Editable | Font can be embedded for editing |
+| Preview & Print | Font can be embedded for viewing only |
+| Restricted | No embedding allowed |
+
+### Checking Embedding Rights
+
+```bash
+# Fontisan can report embedding rights
+fontisan analyze font.ttf --embedding
+```
+
+---
+
+## Common Font Sources & Licenses
+
+| Source | License | Notes |
+|--------|---------|-------|
+| Google Fonts | OFL-1.1, Apache-2.0 | Free, open source |
+| Adobe Fonts | Proprietary | Subscription required |
+| Monotype | Proprietary | Commercial licenses |
+| System fonts | Varies | OS license applies |
+| Microsoft ClearType | Proprietary | Windows bundle |
+
+---
+
+## Best Practices
+
+### For Projects
+
+1. **Document font licenses** in your project
+2. **Use OFL fonts** when possible
+3. **Verify embedding rights** before PDF generation
+4. **Keep license files** alongside fonts
+
+### For CI/CD
+
+1. **Use `--accept-all-licenses`** carefully
+2. **Document which fonts** you use
+3. **Audit license compliance** periodically
+4. **Consider commercial alternatives** for proprietary fonts
+
+### Example: Documenting Font Usage
+
+```yaml
+# fonts.yml with license documentation
+# Project: My Documentation
+# Generated: 2026-03-10
+
+Roboto:  # OFL-1.1 - https://fonts.google.com/specimen/Roboto
+  - Regular
+  - Bold
+
+Source Code Pro:  # OFL-1.1 - https://fonts.google.com/specimen/Source+Code+Pro
+  - Regular
+```
+
+---
+
+## See Also
+
+- [Requirements](/guide/concepts/requirements) - Specifying font needs
+- [Formulas Guide](/guide/formulas) - How formulas work
+- [Exit Codes](/cli/exit-codes) - License error (code 4)
+- [SIL OFL](https://scripts.sil.org/OFL) - Open Font License

data/docs/guide/concepts/requirements.md

@@ -0,0 +1,388 @@
+---
+title: Font Requirements
+---
+
+# Font Requirements
+
+A **Font Requirement** specifies what fonts your project needs. This is the core abstraction that powers Fontist manifests.
+
+## What is a Font Requirement?
+
+A font requirement tells Fontist:
+
+> "I need these specific fonts in these specific styles. Do they exist? If not, install them. Return the paths."
+
+### Requirement Components
+
+A complete font requirement includes:
+
+| Component | Example | Required |
+|-----------|---------|----------|
+| Font name | `"Open Sans"` | Yes |
+| Styles | `Regular`, `Bold` | Optional |
+| Format | `ttf`, `otf` | Optional |
+| Source | Specific formula | Optional |
+
+---
+
+## Manifests: Requirements in YAML
+
+A **manifest** is a YAML file listing font requirements:
+
+```yaml
+# manifest.yml
+Open Sans:
+  - Regular
+  - Bold
+
+Roboto Mono:
+  - Regular
+
+Fira Code: []  # All styles
+```
+
+### How Fontist Processes a Manifest
+
+```
+manifest.yml
+      │
+      ▼
+┌─────────────────┐
+│ Read YAML       │
+│ Requirements    │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│ For each font:  │
+│                 │
+│ Check system    │──▶ Found? ──▶ Return paths
+│ fonts index     │
+└────────┬────────┘
+         │ Not found
+         ▼
+┌─────────────────┐
+│ Check Fontist   │──▶ Found? ──▶ Return paths
+│ fonts directory │
+└────────┬────────┘
+         │ Not found
+         ▼
+┌─────────────────┐
+│ Search formulas │──▶ Found? ──▶ Download & Install
+└────────┬────────┘
+         │
+         ▼
+    Return paths (or error)
+```
+
+---
+
+## CLI Commands
+
+### Install from Manifest
+
+```bash
+# Install all fonts in manifest
+fontist manifest-install manifest.yml
+
+# With license acceptance (for CI)
+fontist manifest-install --accept-all-licenses manifest.yml
+```
+
+### Check Without Installing
+
+```bash
+# Check if fonts are available
+fontist manifest-check manifest.yml
+
+# Returns exit code:
+# 0 = all fonts available
+# 3 = some fonts missing
+```
+
+### Get Locations
+
+```bash
+# Get paths to fonts (install if needed)
+fontist manifest-locations manifest.yml
+```
+
+---
+
+## Manifest Format
+
+### Basic Format
+
+```yaml
+Font Family Name:
+  - Style 1
+  - Style 2
+```
+
+### Examples
+
+```yaml
+# Single font, single style
+Helvetica:
+  - Regular
+
+# Single font, multiple styles
+Open Sans:
+  - Regular
+  - Bold
+  - Italic
+  - Bold Italic
+
+# All available styles
+Fira Code: []
+
+# Multiple fonts
+Roboto:
+  - Regular
+  - Bold
+
+Roboto Mono:
+  - Regular
+```
+
+### Finding Font Names
+
+```bash
+# Search available fonts
+fontist list "Segoe"
+
+# Check specific font
+fontist status "Open Sans"
+```
+
+---
+
+## Ruby API
+
+### From Hash
+
+```ruby
+manifest_hash = {
+  "Open Sans" => ["Regular", "Bold"],
+  "Roboto Mono" => ["Regular"]
+}
+
+manifest = Fontist::Manifest.from_hash(manifest_hash)
+```
+
+### From YAML File
+
+```ruby
+manifest = Fontist::Manifest.from_file("fonts.yml")
+```
+
+### Install and Get Paths
+
+```ruby
+# Install fonts and get locations
+locations = manifest.install(confirmation: "yes")
+
+# Result structure:
+{
+  "Open Sans" => {
+    "Regular" => {
+      "full_name" => "Open Sans",
+      "paths" => ["/path/to/OpenSans-Regular.ttf"]
+    },
+    "Bold" => {
+      "full_name" => "Open Sans Bold",
+      "paths" => ["/path/to/OpenSans-Bold.ttf"]
+    }
+  }
+}
+```
+
+### Get Locations Only
+
+```ruby
+# Get paths without installing
+locations = Fontist::Manifest.from_file("fonts.yml").locations
+```
+
+---
+
+## Use Cases
+
+### CI/CD Pipelines
+
+Ensure fonts are available for document generation:
+
+```yaml
+# .github/workflows/docs.yml
+- name: Install fonts
+  run: |
+    gem install fontist
+    fontist manifest-install --accept-all-licenses fonts.yml
+
+- name: Build PDFs
+  run: bundle exec rake build:pdfs
+```
+
+### Team Development
+
+Share font requirements across team:
+
+```yaml
+# Commit fonts.yml to repository
+Source Sans Pro:
+  - Regular
+  - Bold
+  - Italic
+
+# New team member runs:
+fontist manifest-install fonts.yml
+```
+
+### Document Publishing
+
+Ensure Metanorma/Asciidoctor fonts:
+
+```yaml
+# fonts.yml for document publishing
+Noto Serif:
+  - Regular
+  - Bold
+  - Italic
+
+Source Code Pro:
+  - Regular
+```
+
+---
+
+## Error Handling
+
+### Missing Fonts
+
+```bash
+fontist manifest-check manifest.yml
+# Exit code 3: Font not found
+```
+
+### License Required
+
+```bash
+fontist manifest-install manifest.yml
+# Exit code 4: License needs acceptance
+
+# Solution:
+fontist manifest-install --accept-all-licenses manifest.yml
+```
+
+### Manifest Not Found
+
+```bash
+fontist manifest-install missing.yml
+# Exit code 5: Manifest file not found
+```
+
+### Invalid YAML
+
+```bash
+fontist manifest-install invalid.yml
+# Exit code 6: Manifest could not be read
+```
+
+---
+
+## Integration with Other Tools
+
+### Metanorma
+
+Metanorma uses Fontist for font management:
+
+```ruby
+# In Metanorma configuration
+fontist:
+  manifest: fonts.yml
+```
+
+### Asciidoctor PDF
+
+```yaml
+# asciidoctor-pdf-theme.yml
+font:
+  catalog:
+    Open Sans:
+      normal: OpenSans-Regular.ttf
+      bold: OpenSans-Bold.ttf
+```
+
+### Prawn (Ruby PDF)
+
+```ruby
+require 'fontist'
+
+# Install font
+paths = Fontist::Font.install("Open Sans", confirmation: "yes")
+
+# Use in Prawn
+Prawn::Document.generate("output.pdf") do
+  font paths.first
+  text "Hello, World!"
+end
+```
+
+---
+
+## Best Practices
+
+### 1. Version Control Your Manifest
+
+```bash
+git add fonts.yml
+git commit -m "Add font manifest"
+```
+
+### 2. Document Font Sources
+
+```yaml
+# fonts.yml
+# Fonts for PDF generation
+# License: All fonts are SIL OFL
+
+Roboto:  # Google Fonts, OFL-1.1
+  - Regular
+  - Bold
+```
+
+### 3. Use Specific Styles
+
+```yaml
+# Good: Specific styles
+Open Sans:
+  - Regular
+  - Bold
+
+# Avoid: All styles when not needed
+Open Sans: []  # Downloads everything
+```
+
+### 4. Handle Errors in Scripts
+
+```bash
+#!/bin/bash
+set -e
+
+# Install fonts, handle missing fonts
+if ! fontist manifest-check fonts.yml; then
+  echo "Some fonts not available"
+  exit 1
+fi
+
+fontist manifest-install --accept-all-licenses fonts.yml
+```
+
+---
+
+## See Also
+
+- [Manifests Guide](/guide/manifests) - Detailed manifest documentation
+- [CLI Reference: manifest](/cli/manifest) - Manifest commands
+- [API: Fontist::Manifest](/api/manifest) - Ruby API
+- [CI/CD Integration](/guide/ci) - Using Fontist in CI